Gateway آیراکد

Gateway سازگار با Messages که ترافیک مدل AiraCode رو از طریق آیراچت مسیریابی می‌کنه.

Gateway درخواست‌های سازگار با Messages رو با احراز هویت JWT آیراچت دریافت می‌کنه، lane‌های هوشمند آیرا مثل aira-balanced رو حل می‌کنه، و پاسخ رو به‌صورت stream به CLI برمی‌گردونه.

Endpoint‌ها

POST /v1/messages

این endpoint همون شکل درخواست Messages رو که AiraCode و client‌های سازگار استفاده می‌کنن می‌پذیره. baseURL رو روی Gateway بذار و از یک bearer token آیراچت استفاده کن.

curl -X POST \
  -H "Authorization: Bearer $AIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "aira-balanced",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Who are you?"}]
  }' \
  https://app.airachat.ir/api/airacode/gateway/v1/messages

streaming از Server-Sent Events استفاده می‌کنه.

curl -N -X POST \
  -H "Authorization: Bearer $AIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"aira-fast","stream":true,"max_tokens":64,"messages":[{"role":"user","content":"Say ping"}]}' \
  https://app.airachat.ir/api/airacode/gateway/v1/messages

GET /v1/models

lane‌های هوشمند و شناسه‌های مستقیم provider/model در دسترس از طریق Gateway رو برمی‌گردونه.

curl -H "Authorization: Bearer $AIRA_API_KEY" \
  https://app.airachat.ir/api/airacode/gateway/v1/models

POST /v1/messages/count_tokens

هرجا در دسترس باشه، شمارش token خود provider رو برمی‌گردونه؛ برای مسیرهایی که upstream شمارش نداره، یک تخمین local به‌عنوان fallback.

حل اسم مدل

lane‌های هوشمند مثل aira-code به یک استخر مدلِ انتخاب‌شده برای اون task مسیریابی می‌شن.
شناسه‌های مستقیم به فرمت provider/model وقتی مسیریابی مستقیم مجاز باشه پاس داده می‌شن.
alias‌های ذخیره‌شده و نام‌های سازگار قبل از بررسی allowlist نرمال‌سازی می‌شن.
اسم‌های نامعتبر یا در دسترس‌نبودن، 400 model_not_allowed برمی‌گردونن.

احراز هویت

همهٔ endpoint‌ها به Authorization: Bearer <JWT> نیاز دارن. برای CLI از aira login استفاده کن یا در محیط‌های headless مقدارAIRA_API_KEY رو ست کن.

کلید خودت (BYOK)

اگه ترجیح می‌دی هزینهٔ inference رو مستقیم به provider خودت بدی و از AiraCode فقط به‌عنوان لایهٔ حافظه و شناخت استفاده کنی، به‌جای مسیریابی از Gateway کلید خودت رو ست کن:

export OPENROUTER_API_KEY="sk-or-v1-..."   # or AIRA_BYOK_OPENAI / AIRA_BYOK_ANTHROPIC
aira

توی این حالت فقط عملیات حافظه (recall و save) از AiraCredit خرج می‌کنه؛ هزینهٔ token مستقیم به provider تو می‌ره. تنظیم دائمی BYOK: app.airachat.ir/settings/level؛ جزئیات هزینه در قیمت‌گذاری و اعتبار.

خطاها

401 — bearer token وجود نداره، منقضی شده یا نامعتبره.
402 insufficient_credits — اعتبار AiraCredit کافی نیست؛ با aira topup شارژ کن. جزئیات در قیمت‌گذاری و اعتبار.
400 model_not_allowed — مدل داخل allowlist‌ Gateway نیست.
502 — مدل یا مسیر upstream انتخاب‌شده موقتاً در دسترس نیست.
503 — Gateway تنظیمات لازم provider رو نداره.