
مستندات 1xAi و API
راهنمای کامل برای استفاده از 1xAi: ابتدا راهنمای کاربر، سپس مرجع API برای توسعهدهندهها. از فهرست شروع کن یا از اول تا آخر بخوان.
https://1xai.ir/v1- سازگار با OpenAI
- بدون ویپیان
- صورتحساب تومانی
- ده سرویسدهنده، یک کلید
curl https://1xai.ir/v1/chat/completions \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role":"user","content":"سلام"}]
}'فهرست: ۲۰ بخش
راهنمای کاربر
راهنمای کاربر · ۱
شروع سریع در ۵ دقیقه
اگر عجله داری و فقط میخواهی همین حالا اولین تماسِ موفقت را بفرستی، این شش گام کافی است — از ثبتنام تا دیدنِ مصرف در داشبورد.
گام ۱
ثبتنام + تأیید ایمیل
از صفحهٔ ثبتنام با ایمیلت حساب بساز و روی لینکِ تأییدِ ارسالشده کلیک کن.
گام ۲
تکمیل پروفایل هویتی — یک دقیقه
در /onboarding نامِ کامل، کدِ ملی و شمارهٔ موبایلت را ثبت کن. تا وقتی این پروفایل کامل نشده، ساختِ کلید، شارژ و چت پاسخِ 428 میگیرند.
گام ۳
شارژ موجودی یا کد هدیه
از صفحهٔ شارژ با کارتِ ایرانی پرداخت کن — یا اگر gift code دریافت کردهای، از همان صفحه واردش کن.
گام ۴
ساختِ کلید API
در داشبورد یک کلیدِ
1xai-*صادر کن و فوراً یک نسخهاش را کپی کن (دوباره نشان داده نمیشود).گام ۵
یک تماسِ curl
یک درخواست به
/v1/chat/completionsبفرست — مدل را رویgpt-5،claude-sonnet-4-6یاgemini-2.5-proبگذار.گام ۶
نگاه به مصرف
در /dashboard تماسِ تازهات را با هزینهٔ تومانی، توکنها و مدتزمانش میبینی.
اولین تماس — سه نمونه از ده ارائهدهنده
# OpenAI
curl https://1xai.ir/v1/chat/completions \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5","messages":[{"role":"user","content":"سلام"}]}'
# Anthropic — فقط نامِ مدل را عوض کن
curl https://1xai.ir/v1/chat/completions \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"سلام"}]}'
# Google
curl https://1xai.ir/v1/chat/completions \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"سلام"}]}'راهنمای کاربر · ۲
شروع به کار
استفاده از 1xAi به نصبِ چیزی نیاز ندارد. کافیست حساب بسازی، کلیدِ API دریافت کنی، و آدرس پایهٔ کلاینتت را تغییر دهی.
گام ۱
حساب بساز
از صفحهٔ ثبتنام با ایمیلت ثبتنام کن.
گام ۲
ایمیل را تأیید کن
روی لینکِ تأییدِ ارسالشده به ایمیلت کلیک کن.
گام ۳
موجودی را شارژ کن
از صفحهٔ شارژ با کارتِ ایرانی پرداخت کن.
گام ۴
آزمایش کن
یک پیام در آزمایشگاه بفرست تا اولین پاسخ را بگیری.
راهنمای کاربر · ۳
آشنایی با داشبورد
داشبوردِ تو سه بخشِ اصلی دارد:
- موجودی فعلی
- مبلغی که با هر تماسِ موفق کاهش مییابد.
- کلیدهای API
- فهرستِ کلیدها، با پیشوند، نام، و آخرین استفاده.
- گزارشِ مصرف
- تماسهای اخیر، با مدل، توکن و هزینهٔ تومانیِ هر تماس.
راهنمای کاربر · ۴
راهنمای داشبورد
داشبوردِ 1xAi یک پانلِ سبکِ تکصفحهای نیست — هر بخش برای پاسخ به یک سؤالِ مشخص ساخته شده است: «چقدر مانده؟»، «دیروز چه گذشت؟»، «این کلید کجا خرج میشود؟». این بخش راهنمای کوتاهی از همان قسمتهاست.
- خلاصهٔ موجودی
- بالای صفحه: موجودی فعلی، مصرفِ ۲۴ ساعتِ گذشته، تعدادِ تماسِ موفق/ناموفق و سرعتِ سوختِ روزانه.
- نمودارهای تحلیلی
- نمودارِ روزانهی تماسها، توزیعِ توکنها و سهمِ هر ارائهدهنده — همه بهوقتِ تهران رسم میشوند.
- جستوجوی سمتِ سرور
- بالای جدولِ مصرف، فیلدِ جستوجو روی متن، مدل، ارائهدهنده، وضعیت و بازهٔ زمانی فیلتر میکند — همه به صورتِ سمتِ سرور تا روی صدها هزار ردیف هم کند نشود.
- بزرگنماییِ هر کلید
- روی هر کلیدِ API کلیک کنی، صفحهٔ اختصاصیِ همان کلید باز میشود: نمودار، آخرین تماسها، مدلهای پرمصرفش، و دکمهٔ ابطال.
- تنظیمات و امنیت
- تغییرِ رمز، فعّالسازیِ تأییدِ دومرحلهای، و فهرستِ نشستهای فعّال.
همهی تاریخها و زمانها در داشبورد بهصورتِ خودکار به وقتِ Tehran نمایش داده میشوند — حتی اگر مرورگرت روی منطقهی زمانیِ دیگری باشد.
راهنمای کاربر · ۵
شارژ موجودی
شارژِ حساب از طریقِ Zarinpal انجام میشود. در صفحهٔ شارژ مبلغ را انتخاب کن، به درگاه منتقل میشوی، پس از پرداختِ موفق به سامانه برمیگردی و موجودیات بلافاصله بهروز میشود.
بهدلیلِ محدودیتِ جغرافیاییِ Zarinpal، تماس با درگاه از طریقِ یک ریلایِ داخلِ ایران (pay.1xai.ir) انجام میشود؛ وضعیتِ زندهٔ این مسیر هر دقیقه بررسی میشود و اگر در دسترس نبود، صفحهٔ چکاوت خودکار به روشِ کارتبهکارت سوئیچ میکند.
راهنمای کاربر · ۶
آزمایشگاه
آزمایشگاه ابزاریست برای فرستادنِ یک پیامِ تکنوبتی به مدل بدون نوشتنِ کد. مدل را انتخاب میکنی، پیامِ سیستم (اختیاری) و پیامِ خودت را مینویسی، و پاسخ — بههمراه هزینهٔ تومانیِ همان تماس — نمایش داده میشود.
راهنمای کاربر · ۷
انتخاب مدل مناسب
از یک کلید و یک آدرس، به مدلهای هر ده سرویسدهنده دسترسی داری — OpenAI، Anthropic (Claude)، Google (Gemini) و DeepSeek، و همچنین xAI (Grok)، Moonshot AI (Kimi)، Z.ai (GLM)، Alibaba (Qwen)، MiniMax و Tencent (Hunyuan). مسیریابی فقط بر اساسِ نامِ مدل انجام میشود؛ کافی است فیلدِ model را عوض کنی:
| نام مدل | سرویسدهنده | مثلاً |
|---|---|---|
claude-* | Anthropic | claude-sonnet-4-6 |
gemini-* | gemini-2.5-flash | |
deepseek-* | DeepSeek | deepseek-chat |
grok-*kimi-*glm-*qwen*MiniMax-*hy3hy4-preview | مدلهای Grok، Kimi، GLM، Qwen، MiniMax و Hunyuan | grok-4.6, kimi-k3, glm-5.3, qwen3.7-max, MiniMax-M2.7 |
| بقیهٔ نامها | OpenAI | gpt-5, o3 |
مدلهای سریِ mini / flash / haiku سبک و سریعاند و برای بیشترِ کارهای روزمره کافی هستند. مدلهای قویتر مانند gpt-5، claude-opus-4-7 یا gemini-2.5-pro برای کارهای پیچیدهتر مناسبترند. فهرستِ کاملِ مدلها و قیمتِ تومانی در صفحهٔ مدلها است.
راهنمای کاربر · ۸
اتصال ابزارها به 1xAi
کلیدِ 1xai-* فقط برای کدنویسیِ مستقیم نیست. هر ابزاری که آدرسِ پایهٔ سفارشی بپذیرد — ادیتورِ کد، پلتفرمِ اتوماسیون، رابطِ چتِ سلفهاست — با همین کلید و همین صورتحسابِ تومانی کار میکند. برای محبوبترینها راهنمای جداگانه نوشتهایم: گامهای نصب، تنظیماتِ آماده برای کپی، مدلِ پیشنهادی و رفعِ اشکالهای رایجِ همان ابزار.
نقطهٔ شروع: راهنمای اتصال ابزارها: Cursor، Claude Code، n8n و بقیه — یا مستقیم برو سراغِ راهنمای ابزارِ خودت:
راهنمای کاربر · ۹
پرسشهای پرتکرار
آیا برای استفاده از 1xAi نیاز به VPN دارم؟
آیا اطلاعاتِ من ذخیره میشود؟
چطور بفهمم هر تماس چقدر هزینه داشت؟
آیا کلید 1xAi با SDKهای OpenAI کار میکند؟
آیا 1xAi به مدلهای Claude (کلاد) دسترسی دارد؟
آیا میتوانم از مدلهای Gemini گوگل استفاده کنم؟
چطور از یک کد بینِ OpenAI، Claude و Gemini جابهجا شوم؟
مرجع API.
همهٔ مسیرها روی همین آدرس پایه، با هدرِ Authorization: Bearer 1xai-*:
https://1xai.ir/v1مرجع API · ۱
شروع سریع
گام ۱
حساب بساز و موجودی را شارژ کن
از داشبورد، یک کلید API برای خودت صادر کن.
گام ۲
آدرس پایه را تنظیم کن
در کلاینتِ OpenAI،
base_urlرا بهhttps://1xai.ir/v1تغییر بده.گام ۳
کلید را جای OpenAI بگذار
کلیدِ صادرشده را به جای کلیدِ OpenAI استفاده کن.
گام ۴
درخواست بفرست
درخواستهایت را بهصورت معمول ارسال کن — هیچ تغییرِ دیگری لازم نیست.
مرجع API · ۲
احراز هویت
هر درخواست باید هدرِ Authorization داشته باشد:
Authorization: Bearer 1xai-XXXXXXXXXXXXXXXXXXXXXXXXهر کلید تا ۳۰۰ درخواست در دقیقه میتواند بفرستد (بِرست هم ۳۰۰ است — یعنی همه را میشود یکجا خرج کرد). بیشتر از آن 429 برمیگردد و هدرِ Retry-After میگوید کِی دوباره امتحان کنی.
مرجع API · ۳
اندپوینتهای پشتیبانیشده
curl https://1xai.ir/v1/chat/completions \
-H "Authorization: Bearer 1xai-..." \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role":"user","content":"سلام"}]
}'علاوه بر چت، این اندپوینتهای OpenAI هم از همین آدرسِ پایه در دسترساند: responses، embeddings، images/generations، audio/speech، audio/transcriptions، moderations، models.
مکالمهٔ صوتیِ دوطرفهٔ زنده (Realtime API) راهنمای جداگانه دارد: صوت زنده.
مسیرهایی که فعلاً پشتیبانی نمیشوند
این مسیرها روی حسابهای عادی خطای ۴۰۲ (کد path_unmetered) میدهند، چون هزینهشان را هنوز نمیتوانیم دقیق محاسبه کنیم: Batch و Files، Assistants و Threads، Containers و Vector Stores، Conversations، Fine-tuning، ساخت کلید موقت Realtime (برای تماس صوتی از /v1/realtime/client_secret استفاده کن)، و در Gemini: cachedContents، interactions، files، batches و هر نسخهٔ API جز v1beta و v1 (مثل v1alpha).
ابزارهای سمت سرور code_interpreter، file_search، image_generation و computer_use در Responses و code_execution در Anthropic هم به همین دلیل خطای ۴۰۰ (کد hosted_tool_unmetered) میگیرند. مسیری که در این راهنما نیامده باشد خطای ۴۰۴ (کد path_not_found) میگیرد.
مرجع API · ۴
روتِ نیتیوِ ارائهدهنده
مسیرِ /v1/chat/completions یک وایرفُرمَتِ واحد برای هر ده ارائهدهنده میدهد — ساده، یکدست، و برای بیشترِ کارها کافی. اما لایهٔ سازگاریِ OpenAI در Anthropic و Google چند قابلیتِ کلیدی را بیسروصدا حذف میکند: کشِ پرامپت، فکرِ تَمدیدشده، استنادها، و ابزارهای سمتِ سرور. برای دسترسی به این قابلیتها، 1xAi دو مسیرِ نیتیو هم باز کرده است که مستقیماً به API رسمیِ هر ارائهدهنده وصل میشوند.
- /anthropic/v1/*
- پاسترو به Anthropic Messages API — برای cache_control، thinking، citations و server tools.
- /gemini/v1beta/*
- پاسترو به Google Generative Language API — برای grounding و ابزارهای ویژهی Gemini.
- احراز هویت
- همان کلیدِ 1xai-* تو. نیاز به حسابِ Anthropic یا Google نداری.
- صورتحساب
- همان قاعده — مصرفِ توکن از پاسخ استخراج و به تومان محاسبه میشود.
Anthropic نیتیو — کشِ پرامپت
ساختارِ بدنه دقیقاً همان Messages API رسمیِ Anthropic است. فقط کافی است base_url را به https://1xai.ir/anthropic بدهی و کلیدِ 1xai-* را در هدرِ x-api-key بگذاری. هدرِ anthropic-version الزامی است.
با cache_control
curl https://1xai.ir/anthropic/v1/messages \
-H "x-api-key: 1xai-..." \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "متنِ بسیار طولانیِ راهنما که در همهی تماسها تکرار میشود...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "خلاصهای از این راهنما بده."}
]
}'Anthropic SDK — extended thinking
from anthropic import Anthropic
client = Anthropic(
base_url="https://1xai.ir/anthropic",
api_key="1xai-...",
)
resp = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
thinking={"type": "enabled", "budget_tokens": 2048},
system=[
{
"type": "text",
"text": "راهنمای دامنهی تخصصی... (کلِ این بلوک کش میشود)",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "این مسئلهی منطقی را گامبهگام حل کن."}],
)
print(resp.content[0].text)
# resp.usage.cache_read_input_tokens — توکنهایی که از کش خوانده شد
# resp.usage.cache_creation_input_tokens — توکنهایی که کش ساخته شدبا cache_control اگر بلوکِ سیستم بزرگ باشد، تماسهای بعدی تا حدودِ ۹۰٪ ارزانتر میشوند — توکنهای خواندهشده از کش با قیمتِ پایینتر محاسبه میگردند. مسیرِ /v1/chat/completions این هدر را بیسروصدا حذف میکند؛ مسیرِ نیتیو نه.
Claude Code و SDK رسمی Anthropic
Claude Code هم با همین مسیر کار میکند — دو متغیرِ محیطی کافی است و نیازی به حسابِ Anthropic نداری:
تنظیم با دو متغیر محیطی
export ANTHROPIC_BASE_URL="https://1xai.ir/anthropic"
export ANTHROPIC_AUTH_TOKEN="1xai-..."
claudeبرای SDK رسمی Anthropic هم همان الگوی بالاست: base_url="https://1xai.ir/anthropic" — نمونهٔ کاملِ پایتون را بالاتر دیدی. اگر base_url را روی https://1xai.ir/v1 گذاشته باشی هم کار میکند: دروازه /v1/messages را میشناسد و به همان مسیرِ نیتیو میفرستد. نقطهٔ پایانیِ count_tokens هم در دسترس است — برای شمارشِ توکنِ پرامپت قبل از ارسال.
Gemini نیتیو
مسیرِ /gemini/v1beta/* بهصورتِ کامل به Google Generative Language API پاسترو میشود. ساختارِ بدنه همان generateContent و streamGenerateContent رسمی است. کلیدِ 1xai-* را در هدرِ x-goog-api-key (یا Authorization: Bearer) میفرستی — پارامترِ ?key= پذیرفته نمیشود و پاسخش 401 است؛ کلید حتماً باید در هدر باشد.
curl https://1xai.ir/gemini/v1beta/models/gemini-2.5-flash:generateContent \
-H "x-goog-api-key: 1xai-..." \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "این متن را به یک پاراگراف خلاصه کن."}]}
],
"generationConfig": {
"maxOutputTokens": 1024,
"temperature": 0.3
}
}'Gemini SDK
from google import genai
from google.genai import types
client = genai.Client(
api_key="1xai-...",
http_options=types.HttpOptions(base_url="https://1xai.ir/gemini"),
)
resp = client.models.generate_content(
model="gemini-2.5-flash",
contents="این متن را به یک پاراگراف خلاصه کن.",
)
print(resp.text)کش ضمنی Gemini خودکار است و تخفیف توکنهای کششده در صورتحساب اعمال میشود. ساخت کش صریح (cachedContents) فعلاً پشتیبانی نمیشود.
/v1/chat/completions استفاده کن. اگر سراغِ کشِ پرامپت، thinking یا استنادها میروی — به مسیرِ نیتیوِ همان ارائهدهنده وصل شو. کلید و صورتحساب فرقی نمیکند.مرجع API · ۵
نقاط پایانی اختصاصی هر سرویسدهنده
علاوه بر بحثِ تفصیلیِ بالا، این بخش یک کارتِ مرجعِ فشرده برای دو نقطهٔ پایانیِ پاسترو است — همان چیزی که میخواهی موقعِ کدنویسی نزدیک دستت باشد.
۱. Anthropic — Messages API
نقطهٔ پایانی
POST https://1xai.ir/anthropic/v1/messages
x-api-key: 1xai-XXXXXXXXXXXXXXXXXXXXXXXX
anthropic-version: 2023-06-01
Content-Type: application/json- ساختارِ بدنه دقیقاً همانِ Anthropic رسمی است (پارامتر
model،messages،system، …). - احراز هویت با
x-api-key+anthropic-versionاست — نهAuthorization: Bearer. - از cache_control، بودجهی thinking، استنادها و ابزارهای سمتِ سرور پشتیبانی میکند — قابلیتهایی که لایهٔ سازگاریِ OpenAI بیسروصدا حذف میکند.
cache_control روی یک بلوکِ system
curl https://1xai.ir/anthropic/v1/messages \
-H "x-api-key: 1xai-..." \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "متنِ بسیار طولانیِ راهنما که در همهی تماسها تکرار میشود...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "خلاصهای از این راهنما بده."}
]
}'۲. Google Gemini — generateContent
نقطهٔ پایانی
POST https://1xai.ir/gemini/v1beta/models/{model}:generateContent
x-goog-api-key: 1xai-XXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json
# جایگزین: Authorization: Bearer 1xai-... (هر دو پذیرفته میشوند)
# کوئریاسترینگ ?key=1xai-... پذیرفته نمیشود — کلید فقط در هدر- ساختارِ بدنه دقیقاً همانِ Google Generative Language API رسمی است.
- احراز هویت با
x-goog-api-key— یاAuthorization: Bearerهم پذیرفته میشود. پارامترِ?key=نه. usageMetadataی کامل (شاملِ توکنهای کششده، فکر و کاندیدها) را برمیگرداند؛ کش ضمنی خودکار است و تخفیفش در صورتحساب اعمال میشود.
curl https://1xai.ir/gemini/v1beta/models/gemini-2.5-flash:generateContent \
-H "x-goog-api-key: 1xai-..." \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "این متن را به یک پاراگراف خلاصه کن."}]}
],
"generationConfig": {
"maxOutputTokens": 1024,
"temperature": 0.3
}
}'TL;DRانتخابِ مسیر
برای جابهجاییِ زندهی مدل و سادگیِ کلاینت — از /v1/chat/completions (لایهٔ سازگاریِ OpenAI) استفاده کن. یک کلاینت، یک شکلِ بدنه، هر ده ارائهدهنده.
برای قابلیتهای اختصاصیِ هر ارائهدهنده — cache_control، thinking، استنادها، grounding — از نقطهٔ پایانیِ نیتیو همان ارائهدهنده استفاده کن. کلیدِ 1xai-* همان است و صورتحساب همان جا کسر میشود.
مرجع API · ۶
گزارشگیری از مصرف با کلید شما
مصرفی که در داشبورد میبینی، از طریقِ همین API هم در دسترسِ توست — بدون نیاز به کلیدِ دومی یا توکنِ سشن. هر کلیدِ 1xai-* میتواند گزارشهای صاحبِ خودش را بخواند.
احراز هویت
همان هدرِ Authorization: Bearer 1xai-* که برای چت میفرستی — هیچ اعتبارنامهٔ اضافهای لازم نیست.
نقاط پایانی
| نقطهٔ پایانی | چه برمیگرداند |
|---|---|
| GET /v1/usage | فهرستِ تماسهای ثبتشده. پارامترها: limit، from، to، q، model، provider، status. |
| GET /v1/usage/summary | خلاصهی روزانهی N روزِ گذشته (پارامترِ days=N). برای رسمِ نمودار مناسب است. |
| GET /v1/wallet/transactions | تاریخچهی تراکنشهای کیف پول — شارژها و کسرها، با limit و offset. برای مغایرتگیریِ مالی از اسکریپت. |
| GET /v1/wallet/summary | خلاصهی کیف پول در N روزِ گذشته (پارامترِ days=N): جمعِ شارژ، جمعِ مصرف و تغییرِ خالص؛ بهعلاوهی spendable_toman، اعتبارِ قابلِ خرجِ همین لحظه (کیف پول منهای مبلغِ درخواستهای در جریان، بهعلاوهی اعتبارِ هدیهی همهی مدلها). هشدارِ کم شدنِ اعتبار را در صفحهی شارژ روشن کن تا پیش از خطای 402 ایمیل بگیری. |
| GET /v1/keys | فهرستِ کلیدهای حسابِ تو — با پیشوند، نام و آخرین استفاده. |
| GET /v1/keys/{id} | جزئیاتِ یک کلیدِ مشخص، شاملِ تجمیعِ مصرف. |
آخرین ۵۰ تماسِ موفقِ مدلِ gpt-5
curl "https://1xai.ir/v1/usage?limit=50&status=success&model=gpt-5" \
-H "Authorization: Bearer 1xai-..."خلاصهی ۳۰ روزِ گذشته
curl "https://1xai.ir/v1/usage/summary?days=30" \
-H "Authorization: Bearer 1xai-..."کیف پول — خلاصه و تراکنشها
# خلاصهی کیف پول در ۳۰ روزِ گذشته
curl "https://1xai.ir/v1/wallet/summary?days=30" \
-H "Authorization: Bearer 1xai-..."
# ۲۰ تراکنشِ آخر (شارژ و کسر)
curl "https://1xai.ir/v1/wallet/transactions?limit=20" \
-H "Authorization: Bearer 1xai-..."فهرستِ کلیدها و جزئیاتِ یکی
# فهرستِ همهی کلیدها
curl https://1xai.ir/v1/keys \
-H "Authorization: Bearer 1xai-..."
# جزئیاتِ یک کلیدِ خاص
curl https://1xai.ir/v1/keys/abc123 \
-H "Authorization: Bearer 1xai-..."جستوجو در گزارش
# همهی تماسهای Anthropic در یک بازه، با عبارتِ "خلاصه" در محتوا
curl "https://1xai.ir/v1/usage?provider=anthropic&q=خلاصه&from=2026-06-01&to=2026-06-17" \
-H "Authorization: Bearer 1xai-..."کشیدنِ خلاصه و رسم
import httpx
BASE = "https://1xai.ir"
KEY = "1xai-..."
with httpx.Client(headers={"Authorization": f"Bearer {KEY}"}, timeout=30) as c:
# خلاصهی ۷ روزِ گذشته
summary = c.get(f"{BASE}/v1/usage/summary", params={"days": 7}).json()
for day in summary["days"]:
print(day["date"], day["calls"], day["cost_toman"])
# آخرین ۲۰ تماسِ ناموفق
fails = c.get(f"{BASE}/v1/usage", params={"limit": 20, "status": "error"}).json()
for row in fails["items"]:
print(row["created_at"], row["model"], row["error_message"])مرجع API · ۷
پاسخ استریم
با "stream": true پاسخ بهصورت Server-Sent Events ارسال میشود. 1xAi بهصورت خودکار stream_options.include_usage را اضافه میکند تا بستهبندیِ نهایی شامل آمارِ توکن باشد.
مرجع API · ۸
صورتحساب
موجودی به تومان نگهداری میشود. هزینهٔ هر تماسِ موفق بهصورت خودکار از موجودیِ تو کسر میشود و در «گزارشِ مصرف» داشبورد نمایش داده میشود. درخواستهای ناموفق ثبت میشوند ولی هزینهای ندارند.
سقفِ خروجی و موجودی
اگر max_tokens درخواستت بیشتر از چیزی باشد که موجودیات پوشش میدهد، درخواست رد نمیشود: دروازه سقفِ خروجی را بهاندازهٔ موجودی پایین میآورد و تماس انجام میشود. در این حالت ممکن است پاسخ با finish_reason: "length" تمام شود — یعنی مدل تا جایی که موجودی اجازه میداد نوشت و بریده شد. خطای 402 فقط وقتی برمیگردد که موجودی حتی کفافِ پرامپت بهعلاوهٔ یک توکنِ خروجی را هم ندهد. با شارژِ حساب، پاسخهای بعدی دوباره با طولِ کامل برمیگردند.
مرجع API · ۹
قالبِ پاسخهای خطا
{
"error": {
"message": "موجودی کافی نیست؛ لطفاً حساب خود را شارژ کنید",
"type": "api_error"
}
}مرجع API · ۱۰
کدهای خطای رایج
اکثرِ خطاهایی که در عمل میبینی به چند الگوی مشخص برمیگردند. این فهرست هرکدام را بههمراهِ علتِ ریشهای و راهِ حلِ پیشنهادی نشان میدهد.
- 402
موجودی کافی نیست (حساب خودت)
موجودیِ تومانیِ خودت تمام شده — ربطی به سرویسدهنده ندارد. این خطا فقط وقتی برمیگردد که موجودی حتی کفافِ پرامپت + یک توکنِ خروجی را ندهد؛ کمتر از آن، دروازه سقفِ خروجی را خودش پایین میآورد و تماس انجام میشود (بخشِ صورتحساب). از /topup شارژ کن — تماسهای آینده بلافاصله بعد از پرداختِ موفق کار میکنند.
- 402
قیمتگذاری برای این مدل تعریف نشده است
این مدل هنوز در کاتالوگِ قیمتیِ ما نیست (سیاستِ default-deny: مدلِ بیقیمت رد میشود تا کسی اشتباهی رایگان مصرف نکند). ما هر ۶ ساعت از LiteLLM قیمتها را همگامسازی میکنیم، اما در پنجرهی لحظهی انتشارِ مدل ممکن است نیاز باشد قیمت دستی اضافه شود — به پشتیبانی پیام بده.
- 401
کلید نامعتبر/منقضی/باطل
کلید وجود ندارد، منقضی شده یا توسطِ خودت ابطال شده. یک کلیدِ تازه از داشبورد بساز.
- 428
پروفایل هویتی کامل نشده
بعد از ثبتنام و تأیید ایمیل، تا وقتی پروفایل هویتی (نام کامل، کد ملی، شمارهٔ موبایل) را کامل نکردهای، اندپوینتهای کلید، کیف پول و چت 428 برمیگردانند. به /onboarding برو و یک دقیقه تکمیلش کن.
- 503
اختلال موقت ارائهدهنده
ارائهدهندهٔ بالاسری (OpenAI/Anthropic/Google) موقتاً پاسخ نمیدهد — به موجودی یا کلیدِ تو ربطی ندارد. ما خودکار چند بار retry میکنیم؛ اگر باز هم 503 برگشت، چند دقیقه بعد دوباره امتحان کن.
- 429
محدودیت تعدد
نرخِ درخواستهایت از حدِ مجاز بالاتر رفته: هر کلیدِ API تا ۳۰۰ درخواست در دقیقه میتواند بفرستد (قابلِ مصرف بهصورتِ انفجاری در یک لحظه)، و ارائهدهندهٔ بالاسری هم سقفِ خودش را دارد. هدرِ Retry-After در پاسخ میگوید کِی میتوانی دوباره امتحان کنی؛ این سقف روی هزینه اثری ندارد، فقط سرعت را محدود میکند.
- 5xx
خطای داخلی
مشکل در سمتِ پروکسیِ ما. اگر تکرار شد، با ID درخواست به پشتیبانی پیام بده — لاگها را همان لحظه برایت بررسی میکنیم.
مرجع API · ۱۱
استفاده با SDK
from openai import OpenAI
client = OpenAI(
base_url="https://1xai.ir/v1",
api_key="1xai-...",
)
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "سلام"}],
)
print(resp.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://1xai.ir/v1",
apiKey: "1xai-...",
});
const resp = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "سلام" }],
});
console.log(resp.choices[0].message.content);برای اینکه لازم نباشد هر بار base_url و کلید را دستی بدهی، بستهٔ رسمیِ متنبازِ 1xAi هم هست: همان SDK رسمیِ OpenAI را از پیش تنظیم میکند و محاسبهٔ هزینه به تومان را هم اضافه دارد.
کلید بساز و اولین درخواست را همین حالا بزن.