۱۰۰ هزار تومان هدیهٔ ثبت‌نام، تا ۱ میلیونبا ثبت‌نام گردونهٔ هدیه را بچرخان: دست‌کم ۱۰۰٬۰۰۰ تومان و تا ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه، بدون کارت بانکیگردونهٔ هدیه۱ میلیون برای تو، ۱ میلیون برای دوستتدوستانت را دعوت کن: برای هر دوستی که فعال شود ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه می‌گیری و خودش هم ۱٬۰۰۰٬۰۰۰ تومانجوایز
1xAi
مستندات

مستندات 1xAi و API

راهنمای کامل برای استفاده از 1xAi: ابتدا راهنمای کاربر، سپس مرجع API برای توسعه‌دهنده‌ها. از فهرست شروع کن یا از اول تا آخر بخوان.

آدرس پایهhttps://1xai.ir/v1
  • سازگار با OpenAI
  • بدون وی‌پی‌ان
  • صورت‌حساب تومانی
  • ده سرویس‌دهنده، یک کلید
curl · اولین درخواست
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":"سلام"}]
  }'

فهرست: ۲۰ بخش

راهنمای کاربر · ۱

شروع سریع در ۵ دقیقه

اگر عجله داری و فقط می‌خواهی همین حالا اولین تماسِ موفقت را بفرستی، این شش گام کافی است — از ثبت‌نام تا دیدنِ مصرف در داشبورد.

  1. گام ۱

    ثبت‌نام + تأیید ایمیل

    از صفحهٔ ثبت‌نام با ایمیلت حساب بساز و روی لینکِ تأییدِ ارسال‌شده کلیک کن.

  2. گام ۲

    تکمیل پروفایل هویتی — یک دقیقه

    در /onboarding نامِ کامل، کدِ ملی و شمارهٔ موبایلت را ثبت کن. تا وقتی این پروفایل کامل نشده، ساختِ کلید، شارژ و چت پاسخِ 428 می‌گیرند.

  3. گام ۳

    شارژ موجودی یا کد هدیه

    از صفحهٔ شارژ با کارتِ ایرانی پرداخت کن — یا اگر gift code دریافت کرده‌ای، از همان صفحه واردش کن.

  4. گام ۴

    ساختِ کلید API

    در داشبورد یک کلیدِ 1xai-* صادر کن و فوراً یک نسخه‌اش را کپی کن (دوباره نشان داده نمی‌شود).

  5. گام ۵

    یک تماسِ curl

    یک درخواست به /v1/chat/completions بفرست — مدل را روی gpt-5، claude-sonnet-4-6 یا gemini-2.5-pro بگذار.

  6. گام ۶

    نگاه به مصرف

    در /dashboard تماسِ تازه‌ات را با هزینهٔ تومانی، توکن‌ها و مدت‌زمانش می‌بینی.

اولین تماس — سه نمونه از ده ارائه‌دهنده

curl
# 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 دریافت کنی، و آدرس پایهٔ کلاینتت را تغییر دهی.

  1. گام ۱

    حساب بساز

    از صفحهٔ ثبت‌نام با ایمیلت ثبت‌نام کن.

  2. گام ۲

    ایمیل را تأیید کن

    روی لینکِ تأییدِ ارسال‌شده به ایمیلت کلیک کن.

  3. گام ۳

    موجودی را شارژ کن

    از صفحهٔ شارژ با کارتِ ایرانی پرداخت کن.

  4. گام ۴

    آزمایش کن

    یک پیام در آزمایشگاه بفرست تا اولین پاسخ را بگیری.

راهنمای کاربر · ۳

آشنایی با داشبورد

داشبوردِ تو سه بخشِ اصلی دارد:

موجودی فعلی
مبلغی که با هر تماسِ موفق کاهش می‌یابد.
کلیدهای 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-*Anthropicclaude-sonnet-4-6
gemini-*Googlegemini-2.5-flash
deepseek-*DeepSeekdeepseek-chat
grok-*kimi-*glm-*qwen*MiniMax-*hy3hy4-previewمدل‌های Grok، Kimi، GLM، Qwen، MiniMax و Hunyuangrok-4.6, kimi-k3, glm-5.3, qwen3.7-max, MiniMax-M2.7
بقیهٔ نام‌هاOpenAIgpt-5, o3

مدل‌های سریِ mini / flash / haiku سبک و سریع‌اند و برای بیشترِ کارهای روزمره کافی هستند. مدل‌های قوی‌تر مانند gpt-5، claude-opus-4-7 یا gemini-2.5-pro برای کارهای پیچیده‌تر مناسب‌ترند. فهرستِ کاملِ مدل‌ها و قیمتِ تومانی در صفحهٔ مدل‌ها است.

راهنمای کاربر · ۸

اتصال ابزارها به 1xAi

کلیدِ 1xai-* فقط برای کدنویسیِ مستقیم نیست. هر ابزاری که آدرسِ پایهٔ سفارشی بپذیرد — ادیتورِ کد، پلتفرمِ اتوماسیون، رابطِ چتِ سلف‌هاست — با همین کلید و همین صورت‌حسابِ تومانی کار می‌کند. برای محبوب‌ترین‌ها راهنمای جداگانه نوشته‌ایم: گام‌های نصب، تنظیماتِ آماده برای کپی، مدلِ پیشنهادی و رفعِ اشکال‌های رایجِ همان ابزار.

نقطهٔ شروع: راهنمای اتصال ابزارها: Cursor‏، Claude Code‏، n8n و بقیه — یا مستقیم برو سراغِ راهنمای ابزارِ خودت:

راهنمای کاربر · ۹

پرسش‌های پرتکرار

آیا برای استفاده از 1xAi نیاز به VPN دارم؟

نه. کلِ ایده‌ی 1xAi همین است: تو از داخلِ ایران مستقیماً به API ما وصل می‌شوی و ما کلیدِ بومی، آدرسِ ایرانی و صورت‌حسابِ تومانی فراهم می‌کنیم.

آیا اطلاعاتِ من ذخیره می‌شود؟

1xAi درخواست‌هایت را به سرویس‌دهندهٔ همان مدل (OpenAI‏، Anthropic یا Google) ارسال می‌کند و فقط متادیتای حداقلی (مدل، توکن، وضعیت، زمان) را برای گزارشِ مصرف نگه می‌دارد. متن پیام‌ها، فایل‌های صوتی و تصاویر در گزارش‌ها ذخیره نمی‌شوند.

چطور بفهمم هر تماس چقدر هزینه داشت؟

در داشبورد و در پایانِ هر تماسِ آزمایشگاه، هزینه‌ی تومانیِ همان تماس نمایش داده می‌شود. تاریخچه‌ی کاملِ مصرف هم در صفحه‌ی گزارشِ مصرف قابلِ مشاهده است.

آیا کلید 1xAi با SDKهای OpenAI کار می‌کند؟

بله، کاملاً سازگار است. در کلاینت‌های Python, Node, Go, .NET و هر کلاینت دیگری کافی است base_url را به https://1xai.ir/v1 تغییر دهی و کلید را با کلیدی که از داشبوردِ ما می‌گیری جایگزین کنی. همان کلاینت و همان کلید به مدل‌های Claude و Gemini هم وصل می‌شود.

آیا 1xAi به مدل‌های Claude (کلاد) دسترسی دارد؟

بله. مدل‌های Anthropic مانندِ claude-opus-4-7‏، claude-sonnet-4-6 و claude-haiku-4-5 از همان آدرسِ /v1/chat/completions در دسترس‌اند. کافی است فیلدِ model را روی نامِ مدلِ Claude بگذاری — هر نامی که با claude- شروع شود به‌صورت خودکار به Anthropic مسیریابی می‌شود. کلید و آدرسِ پایه تغییری نمی‌کند.

آیا می‌توانم از مدل‌های Gemini گوگل استفاده کنم؟

بله. مدل‌های Google مانندِ gemini-2.5-pro‏، gemini-2.5-flash و gemini-2.0-flash از همان API در دسترس‌اند. هر نامِ مدلی که با gemini- یا gemma- شروع شود به Google مسیریابی می‌شود — بدونِ تغییرِ کد یا کلید.

چطور از یک کد بینِ OpenAI‏، Claude و Gemini جابه‌جا شوم؟

فقط فیلدِ model را عوض کن. کلاینتِ OpenAI، آدرسِ پایه و کلیدِ 1xAi ثابت می‌مانند؛ 1xAi درخواست را بر اساسِ نامِ مدل به سرویس‌دهندهٔ درست می‌فرستد: claude-* به Anthropic‏، gemini-*/gemma-* به Google‏، deepseek-* به DeepSeek؛ grok-*، kimi-*، glm-*، qwen*، MiniMax-*، hy3 و hy4-preview هم مدل‌های Grok‏، Kimi‏، GLM‏، Qwen‏، MiniMax و Hunyuan را صدا می‌زنند، و بقیه به OpenAI می‌رود.
بخش دوم

مرجع API.

همهٔ مسیرها روی همین آدرس پایه، با هدرِ Authorization: Bearer 1xai-*:

آدرس پایهhttps://1xai.ir/v1

مرجع API · ۱

شروع سریع

  1. گام ۱

    حساب بساز و موجودی را شارژ کن

    از داشبورد، یک کلید API برای خودت صادر کن.

  2. گام ۲

    آدرس پایه را تنظیم کن

    در کلاینتِ OpenAI، base_url را به https://1xai.ir/v1 تغییر بده.

  3. گام ۳

    کلید را جای OpenAI بگذار

    کلیدِ صادرشده را به جای کلیدِ OpenAI استفاده کن.

  4. گام ۴

    درخواست بفرست

    درخواست‌هایت را به‌صورت معمول ارسال کن — هیچ تغییرِ دیگری لازم نیست.

مرجع API · ۲

احراز هویت

هر درخواست باید هدرِ Authorization داشته باشد:

http
Authorization: Bearer 1xai-XXXXXXXXXXXXXXXXXXXXXXXX

هر کلید تا ۳۰۰ درخواست در دقیقه می‌تواند بفرستد (بِرست هم ۳۰۰ است — یعنی همه را می‌شود یک‌جا خرج کرد). بیشتر از آن 429 برمی‌گردد و هدرِ Retry-After می‌گوید کِی دوباره امتحان کنی.

مرجع API · ۳

اندپوینت‌های پشتیبانی‌شده

POST /v1/chat/completions
curl
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 الزامی است.

POST /anthropic/v1/messages

با cache_control

curl
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

Python
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 نداری:

تنظیم با دو متغیر محیطی

Claude Code
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 است؛ کلید حتماً باید در هدر باشد.

POST /gemini/v1beta/models/{model}:generateContent
curl
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

Python
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

نقطهٔ پایانی

http
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
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

نقطهٔ پایانی

http
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 — generateContent
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
curl "https://1xai.ir/v1/usage?limit=50&status=success&model=gpt-5" \
  -H "Authorization: Bearer 1xai-..."

خلاصه‌ی ۳۰ روزِ گذشته

curl
curl "https://1xai.ir/v1/usage/summary?days=30" \
  -H "Authorization: Bearer 1xai-..."

کیف پول — خلاصه و تراکنش‌ها

curl
# خلاصه‌ی کیف پول در ۳۰ روزِ گذشته
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
# فهرستِ همه‌ی کلیدها
curl https://1xai.ir/v1/keys \
  -H "Authorization: Bearer 1xai-..."

# جزئیاتِ یک کلیدِ خاص
curl https://1xai.ir/v1/keys/abc123 \
  -H "Authorization: Bearer 1xai-..."

جست‌وجو در گزارش

curl
# همه‌ی تماس‌های Anthropic در یک بازه، با عبارتِ "خلاصه" در محتوا
curl "https://1xai.ir/v1/usage?provider=anthropic&q=خلاصه&from=2026-06-01&to=2026-06-17" \
  -H "Authorization: Bearer 1xai-..."

کشیدنِ خلاصه و رسم

Python (httpx)
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 · ۹

قالبِ پاسخ‌های خطا

json
{
  "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

Python
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)
JavaScript
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 را از پیش تنظیم می‌کند و محاسبهٔ هزینه به تومان را هم اضافه دارد.

کلید بساز و اولین درخواست را همین حالا بزن.