مستندات.

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

1. 01

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

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

2. 02

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

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

3. 03

   ساختِ کلید API

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

4. 04

   یک تماسِ curl

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

5. 05

   نگاه به مصرف

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

1. 01

   حساب بساز

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

2. 02

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

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

3. 03

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

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

4. 04

   آزمایش کن

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

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

موجودی فعلی

مبلغی که با هر تماسِ موفق کاهش می‌یابد.

کلیدهای API

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

گزارشِ مصرف

تماس‌های اخیر، با مدل، توکن و هزینهٔ تومانیِ هر تماس.

داشبوردِ 1xAi یک پانلِ سبکِ تک‌صفحه‌ای نیست — هر بخش برای پاسخ به یک سؤالِ مشخص ساخته شده است: «چقدر مانده؟»، «دیروز چه گذشت؟»، «این کلید کجا خرج می‌شود؟». این بخش راهنمای کوتاهی از همان قسمت‌هاست.

خلاصهٔ موجودی

بالای صفحه: موجودی فعلی، مصرفِ ۲۴ ساعتِ گذشته، تعدادِ تماسِ موفق/ناموفق و سرعتِ سوختِ روزانه.

نمودارهای تحلیلی

نمودارِ روزانه‌ی تماس‌ها، توزیعِ توکن‌ها و سهمِ هر ارائه‌دهنده — همه به‌وقتِ تهران رسم می‌شوند.

جست‌وجوی سمتِ سرور

بالای جدولِ مصرف، فیلدِ جست‌وجو روی متن، مدل، ارائه‌دهنده، وضعیت و بازهٔ زمانی فیلتر می‌کند — همه به صورتِ سمتِ سرور تا روی صدها هزار ردیف هم کند نشود.

بزرگ‌نماییِ هر کلید

روی هر کلیدِ API کلیک کنی، صفحهٔ اختصاصیِ همان کلید باز می‌شود: نمودار، آخرین تماس‌ها، مدل‌های پرمصرفش، و دکمهٔ ابطال.

تنظیمات و امنیت

تغییرِ رمز، فعّال‌سازیِ تأییدِ دومرحله‌ای، و فهرستِ نشست‌های فعّال.

همه‌ی تاریخ‌ها و زمان‌ها در داشبورد به‌صورتِ خودکار به وقتِ Tehran نمایش داده می‌شوند — حتی اگر مرورگرت روی منطقه‌ی زمانیِ دیگری باشد.

شارژِ حساب از طریقِ Zarinpal انجام می‌شود. در صفحهٔشارژمبلغ را انتخاب کن، به درگاه منتقل می‌شوی، پس از پرداختِ موفق به سامانه برمی‌گردی و موجودی‌ات بلافاصله به‌روز می‌شود.

به‌دلیلِ محدودیتِ جغرافیاییِ Zarinpal، تماس با درگاه از طریقِ یک ریلایِ داخلِ ایران (pay.1xai.ir) انجام می‌شود؛ وضعیتِ زندهٔ این مسیر هر دقیقه بررسی می‌شود و اگر در دسترس نبود، صفحهٔ چک‌اوت خودکار به روشِ کارت‌به‌کارت سوئیچ می‌کند.

آزمایشگاهابزاری‌ست برای فرستادنِ یک پیامِ تک‌نوبتی به مدل بدون نوشتنِ کد. مدل را انتخاب می‌کنی، پیامِ سیستم (اختیاری) و پیامِ خودت را می‌نویسی، و پاسخ — به‌همراه هزینهٔ تومانیِ همان تماس — نمایش داده می‌شود.

از یک کلید و یک آدرس، به مدل‌های هر سه سرویس‌دهنده دسترسی داری —OpenAI، Anthropic (Claude) و Google (Gemini). مسیریابی فقط بر اساسِ نامِ مدل انجام می‌شود؛ کافی است فیلدِ model را عوض کنی:

• — claude-* به Anthropic (مثلاً claude-sonnet-4-6)
• — gemini-* به Google (مثلاً gemini-2.5-flash)
• — بقیهٔ نام‌ها به OpenAI (مثلاً gpt-5، o3)

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

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

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

• اتصال Cursor
• اتصال Claude Code
• اتصال n8n
• اتصال Cline
• اتصال Open WebUI
• اتصال Continue

1. 01

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

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

2. 02

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

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

3. 03

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

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

4. 04

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

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

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

Authorization: Bearer 1xai-XXXXXXXXXXXXXXXXXXXXXXXX

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 نیز از همین آدرسِ پایه در دسترس‌اند: embeddings، images/generations،audio/speech، audio/transcriptions،moderations، files، models.

مسیرِ /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 — برای cachedContents، grounding و ابزارهای ویژه‌ی Gemini.

احراز هویت

همان کلیدِ 1xai-* تو. نیاز به حسابِ Anthropic یا Google نداری.

صورت‌حساب

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

Anthropic نیتیو — کشِ پرامپت

ساختارِ بدنه دقیقاً همان Messages API رسمیِ Anthropic است. فقط کافی است base_url را به https://1xai.ir/anthropic بدهی و کلیدِ 1xai-* را در هدرِ x-api-key بگذاری. هدرِ anthropic-version الزامی است.

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": "خلاصه‌ای از این راهنما بده."}
    ]
  }'

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 این هدر را بی‌سروصدا حذف می‌کند؛ مسیرِ نیتیو نه.

Gemini نیتیو — cachedContents

مسیرِ /gemini/v1beta/* به‌صورتِ کامل به Google Generative Language API پاس‌ترو می‌شود. ساختارِ بدنه همان generateContent و streamGenerateContent رسمی است. کلیدِ 1xai-* را در پارامترِ ?key= یا هدرِ x-goog-api-key می‌فرستی.

curl "https://1xai.ir/gemini/v1beta/models/gemini-2.5-flash:generateContent?key=1xai-..." \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "این متن را به یک پاراگراف خلاصه کن."}]}
    ],
    "generationConfig": {
      "maxOutputTokens": 1024,
      "temperature": 0.3
    }
  }'

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"),
)

# گامِ ۱: یک cachedContent با محتوای پرتکرار بساز.
cache = client.caches.create(
    model="gemini-2.5-flash",
    config=types.CreateCachedContentConfig(
        contents=[
            types.Content(
                role="user",
                parts=[types.Part.from_text("کلِ متنِ کتاب یا مستند بزرگ اینجا...")],
            )
        ],
        ttl="3600s",
    ),
)

# گامِ ۲: از کش در چند تماسِ بعدی استفاده کن — هزینه‌ی توکنِ ورودی به‌شدت کاهش می‌یابد.
resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="فصلِ سوم را خلاصه کن.",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(resp.text)

cachedContents یک منبعِ مستقل در APIی Google است که از طریقِ لایهٔ سازگاریِ OpenAI اصلاً قابلِ دسترس نیست. اگر متنِ پایه‌ات بزرگ است (راهنما، کتاب، کد، تاریخچهٔ گفتگو) و در تماس‌های متوالی تکرار می‌شود، مسیرِ نیتیو هزینه‌ی ورودی را تا حدِ یک‌سومِ قیمتِ معمولی می‌رساند.

انتخابِ مسیر: اگر فقط چت‌های ساده، تعویضِ زنده‌ی مدل بینِ سه ارائه‌دهنده، یا کارهای استاندارد می‌خواهی — از /v1/chat/completions استفاده کن. اگر سراغِ کشِ پرامپت، thinking، استنادها، یا cachedContents می‌روی — به مسیرِ نیتیوِ همان ارائه‌دهنده وصل شو. کلید و صورت‌حساب فرقی نمی‌کند.

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

۱. 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 بی‌سروصدا حذف می‌کند.

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 هم پذیرفته می‌شود.
• — از cachedContents و 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
    }
  }'

مصرفی که در داشبورد می‌بینی، از طریقِ همین API هم در دسترسِ توست — بدون نیاز به کلیدِ دومی یا توکنِ سشن. هر کلیدِ 1xai-* می‌تواند گزارش‌های صاحبِ خودش را بخواند.

احراز هویت

همان هدرِ Authorization: Bearer 1xai-* که برای چت می‌فرستی — هیچ اعتبارنامهٔ اضافه‌ای لازم نیست.

نقاط پایانی

GET /v1/usage

فهرستِ تماس‌های ثبت‌شده. پارامترها: limit، from، to، q، model، provider، status.

GET /v1/usage/summary

خلاصه‌ی روزانه‌ی N روزِ گذشته (پارامترِ days=N). برای رسمِ نمودار مناسب است.

GET /v1/keys

فهرستِ کلیدهای حسابِ تو — با پیشوند، نام و آخرین استفاده.

GET /v1/keys/{id}

جزئیاتِ یک کلیدِ مشخص، شاملِ تجمیعِ مصرف.

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/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"])

با "stream": true پاسخ به‌صورت Server-Sent Events ارسال می‌شود. 1xAi به‌صورت خودکار stream_options.include_usage را اضافه می‌کند تا بسته‌بندیِ نهایی شامل آمارِ توکن باشد.

موجودی به تومان نگه‌داری می‌شود. هزینهٔ هر تماسِ موفق به‌صورت خودکار از موجودیِ تو کسر می‌شود و در «گزارشِ مصرف» داشبورد نمایش داده می‌شود. درخواست‌های ناموفق ثبت می‌شوند ولی هزینه‌ای ندارند.

اکثرِ خطاهایی که در عمل می‌بینی به چند الگوی مشخص برمی‌گردند. این فهرست هرکدام را به‌همراهِ علتِ ریشه‌ای و راهِ حلِ پیشنهادی نشان می‌دهد.

402 موجودی ناکافی

موجودیِ تومانیِ حسابت کفافِ این تماس را نمی‌دهد. از /topup شارژ کن — تماس‌های آینده بلافاصله بعد از پرداختِ موفق کار می‌کنند.

402 قیمت‌گذاری برای این مدل تعریف نشده است

این مدل هنوز در کاتالوگِ قیمتیِ ما نیست (سیاستِ default-deny: مدلِ بی‌قیمت رد می‌شود تا کسی اشتباهی رایگان مصرف نکند). ما هر ۶ ساعت از LiteLLM قیمت‌ها را همگام‌سازی می‌کنیم، اما در پنجره‌ی لحظه‌ی انتشارِ مدل ممکن است نیاز باشد قیمت دستی اضافه شود — به پشتیبانی پیام بده.

401 کلید نامعتبر/منقضی/باطل

کلید وجود ندارد، منقضی شده یا توسطِ خودت ابطال شده. یک کلیدِ تازه از داشبورد بساز.

503 سرویس‌دهنده در دسترس نیست

ارائه‌دهندهٔ بالاسری (OpenAI/Anthropic/Google) موقتاً پاسخ نمی‌دهد. ما خودکار چند بار retry می‌کنیم — اگر باز هم 503 برگشت، چند ثانیه صبر کن و دوباره بزن.

429 محدودیت تعدد

نرخِ درخواست‌هایت از حدِ تعیین‌شده‌ی ارائه‌دهنده یا حسابِ ما بالاتر رفته. هدرِ Retry-After در پاسخ می‌گوید کِی می‌توانی دوباره امتحان کنی.

5xx خطای داخلی

مشکل در سمتِ پروکسیِ ما. اگر تکرار شد، با ID درخواست به پشتیبانی پیام بده — لاگ‌ها را همان لحظه برایت بررسی می‌کنیم.

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

• کدِ متن‌باز و کوک‌بوک در گیت‌هاب
• بستهٔ Node در npm — npm install 1xai-sdk
• بستهٔ Python در PyPI — pip install 1xai-sdk