مستندات API

IranRouter یک HTTP API سازگار با OpenAI ارائه می‌دهد.

آدرس پایه

https://iranrouter.net/api/v1

احراز هویت

هدر Authorization: Bearer ir-… را از داشبورد ← کلیدهای API بفرستید. پاسخ‌های موفق chat شامل X-Request-Id هستند.

فهرست مدل‌ها

GET /api/v1/models

بررسی کلید / اعتبار

GET /api/v1/key
Authorization: Bearer $IRANROUTER_API_KEY

پاسخ شامل free_requests_remaining، free_models و topup_url است.

سطح رایگان

هر ایمیل 20 درخواست رایگان chat مشترک روی deepseek/deepseek-flash و openai/gpt-4o-mini می‌گیرد. فراخوانی‌های رایگان با iranrouter.billed_as = "free" ثبت می‌شوند و اعتبار را کم نمی‌کنند. وقتی سهمیه تمام شود (و کیف پول خالی باشد)، API کد HTTP 402 برمی‌گرداند:

{
  "error": {
    "message": "Free quota exhausted (20 requests on deepseek-flash / GPT-4o-mini). Charge your account to continue. Top up here: https://iranrouter.net/dashboard/credits",
    "type": "insufficient_quota",
    "code": "free_quota_exhausted",
    "topup_url": "https://iranrouter.net/dashboard/credits"
  }
}

جستجوی generation

GET /api/v1/generation/{request_id}
Authorization: Bearer $IRANROUTER_API_KEY

از iranrouter.request_id / X-Request-Id پاسخ chat استفاده کنید.

محدودیت نرخ

مسیرهای احراز هویت‌شده X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset برمی‌گردانند (۶۰ درخواست / ۶۰ثانیه به ازای هر کلید).

Chat completions

POST /api/v1/chat/completions
Content-Type: application/json
Authorization: Bearer $IRANROUTER_API_KEY

{
  "model": "iranrouter/demo-chat",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "temperature": 0.7,
  "max_tokens": 512,
  "seed": 42,
  "stream": false
}

همچنین top_p، stop، جریمه‌ها، response_format، tools، بخش‌های multipart در content و ترجیحات provider به‌سبک OpenRouter را می‌پذیرد. خطاهای اعتبارسنجی / احراز هویت با فرمت OpenAI یعنی {"error":{message,type,code,param}} هستند.

Streaming

"stream": true را برای SSE به‌سبک OpenAI (text/event-stream) بگذارید؛ با data: [DONE] تمام می‌شود. chunk نهایی وقتی stream_options.include_usage true باشد (پیش‌فرض) شامل usage است.

Embeddings

POST /api/v1/embeddings
Authorization: Bearer $IRANROUTER_API_KEY

{
  "model": "iranrouter/demo-embed",
  "input": "سلام دنیا",
  "dimensions": 1536,
  "encoding_format": "float"
}

تصاویر (BFL / FLUX)

تولید تصویر سازگار با OpenAI که به Black Forest Labs (api.bfl.ai) مسیریابی می‌شود. مدل‌ها: bfl/flux-2-pro، bfl/flux-2-klein-4b، bfl/flux-pro-1.1.

POST /api/v1/images/generations
Authorization: Bearer $IRANROUTER_API_KEY

{
  "model": "bfl/flux-2-pro",
  "prompt": "a teal fox in the desert at dusk",
  "size": "1024x1024"
}

ویدیو (BFL FLUX 3)

ویدیوی async BFL تا آماده شدن در سمت سرور poll می‌شود. حالت‌ها: t2v، i2v (keyframes)، v2v (start_video).

POST /api/v1/videos/generations
Authorization: Bearer $IRANROUTER_API_KEY

{
  "model": "bfl/flux-3-video",
  "prompt": "waves crashing at sunset, cinematic",
  "mode": "t2v",
  "duration": 5,
  "resolution": "hd",
  "aspect_ratio": "16:9",
  "generate_audio": true
}

ترجیحات ارائه‌دهنده

شیء اختیاری provider به‌سبک OpenRouter برای کنترل ترتیب / ignore / fallback.

{
  "provider": {
    "order": ["mock-fallback", "mock-primary"],
    "ignore": ["mock-fail"],
    "allow_fallbacks": true
  }
}

رفتار Fallback

هر مدل می‌تواند چند endpoint ارائه‌دهنده با اولویت داشته باشد. روتر آن‌ها را به‌ترتیب امتحان می‌کند. iranrouter/demo-chat را امتحان کنید — اولین endpoint طوری تنظیم شده که خطا بدهد تا failover را در metadata پاسخ ببینید.

Upstreamهای زنده

UPSTREAM_OPENAI_API_KEY، UPSTREAM_ANTHROPIC_API_KEY، UPSTREAM_DEEPSEEK_API_KEY یا UPSTREAM_BFL_API_KEY را در .env بگذارید، سپس دوباره seed کنید. بدون آن‌ها، درایورهای mock استک را به‌صورت محلی قابل اجرا نگه می‌دارند (از جمله تصویر/ویدیوی BFL).