مستندات.

استفاده از 1xAi به نصبِ چیزی نیاز ندارد. کافی‌ست حساب بسازی، کلیدِ API دریافت کنی، و آدرس پایهٔ کلاینتت را تغییر دهی.

1. 01

   حساب بساز

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

2. 02

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

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

3. 03

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

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

4. 04

   آزمایش کن

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

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

موجودی فعلی

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

کلیدهای API

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

گزارشِ مصرف

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

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

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

از یک کلید و یک آدرس، به مدل‌های هر سه سرویس‌دهنده دسترسی داری —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 برای کارهای پیچیده‌تر مناسب‌ترند. فهرستِ کاملِ مدل‌ها و قیمتِ تومانی در صفحهٔ مدل‌ها است.

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 می‌روی — به مسیرِ نیتیوِ همان ارائه‌دهنده وصل شو. کلید و صورت‌حساب فرقی نمی‌کند.

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

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