Basirat Gateway

مستندات

⁨Basirat Gateway⁩ با OpenAI سازگار است. کافی است در هر SDK سازگار با OpenAI آدرس پایه و کلید را عوض کنید تا به همه مدل‌ها دسترسی داشته باشید.

شروع سریع

یک کلید API بسازید، اعتبار بخرید و SDK خود را به درگاه وصل کنید. نام مدل‌ها به این شکل است: provider/model.

from openai import OpenAI

client = OpenAI(base_url="https://api.example.com/v1", api_key="sk-bf-...")

resp = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a haiku about routers."}],
)
print(resp.choices[0].message.content)
print("cost:", resp.usage.cost)
مسیرها: /v1/chat/completions, /v1/responses, /v1/completions, /v1/embeddings, /v1/models، و همچنین مسیر Anthropic /anthropic/v1/messages و مسیر Gemini /genai .

مدل‌های جایگزین

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

{
  "models": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o", "openai/gpt-4o-mini"],
  "messages": [{"role": "user", "content": "Hello"}]
}

شکل اصلی "model": "...", "fallbacks": ["..."] هم کار می‌کند.

الگوها

در پنل یک الگو بسازید و نام آن را به‌جای مدل بفرستید. الگو مدل، مدل‌های جایگزین، دستور سیستمی و پارامترهای پیش‌فرض را تعیین می‌کند و هر چیزی که در درخواست بفرستید جایگزین پیش‌فرض‌ها می‌شود.

{"model": "@preset/support-bot", "messages": [{"role": "user", "content": "Where is my order?"}]}

استریم و هزینه

مقدار "stream": true را برای دریافت استریم (server-sent events) تنظیم کنید. هر پاسخ — استریم یا عادی — شامل usage.cost.total_cost به دلار است. هر درخواست را بعداً می‌توانید این‌طور پیدا کنید:

curl "https://api.example.com/api/v1/generation?id=<request-id>" -H "Authorization: Bearer $API_KEY"

مشاهده سقف باقی‌مانده کلید و موجودی حساب:

curl https://api.example.com/api/v1/key -H "Authorization: Bearer $API_KEY"
curl https://api.example.com/api/v1/credits -H "Authorization: Bearer $API_KEY"

خطاها و محدودیت‌ها

401invalid_api_key / key_expiredکلید ارسال نشده، اشتباه است، تعویض شده یا منقضی شده است.
402insufficient_creditsموجودی حساب تمام شده است. اعتبار بخرید.
402key_limit_exceededکلید در این دوره به سقف هزینه رسیده است.
403key_disabled / model_not_pricedکلید غیرفعال است یا امکان محاسبه هزینه این مدل وجود ندارد.
404model_not_foundاین مدل در فهرست مدل‌ها نیست.
429rate_limitedتعداد درخواست‌ها زیاد است. پس از زمان سرآیند Retry-After دوباره تلاش کنید.

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

API مدیریت کلیدها

یک کلید مدیریتی در پنل بسازید تا کلیدها را با کد صادر کنید — مثلاً برای هر مشتری سرویس خودتان یک کلید با سقف جداگانه.

curl -X POST https://api.example.com/api/v1/keys \
  -H "Authorization: Bearer sk-mgmt-..." -H "Content-Type: application/json" \
  -d '{"name": "customer-42", "limit": 10, "limit_reset": "monthly"}'

همچنین در دسترس: GET /api/v1/keys, GET|PATCH|DELETE /api/v1/keys/:id.

OAuth برای برنامه‌ها (PKCE)

به کاربرانتان اجازه دهید حساب خودشان را وصل کنند و هزینه مصرف خود را بپردازند. آن‌ها را به صفحه تأیید هدایت کنید و کد برگشتی را با یک کلید عوض کنید.

https://api.example.com/oauth/authorize?callback_url=https://yourapp.com/cb&code_challenge=<S256 challenge>&code_challenge_method=S256

curl -X POST https://api.example.com/api/v1/auth/keys -H "Content-Type: application/json" \
  -d '{"code": "<code>{tr("", "code_verifier": "")}<verifier>", "code_challenge_method": "S256"}'

معرفی برنامه

سرآیندهای HTTP-Referer و X-Title را ارسال کنید تا در رتبه‌بندی عمومی نمایش داده شوید و درخواست‌هایتان در فعالیت‌ها برچسب بخورد.

-H "HTTP-Referer: https://yourapp.com" -H "X-Title: Your App"