مستندات API بینوباکس

آدرس پایه

پیشوند همهٔ مسیرها:

از binobox.ir/api/v1 استفاده نکنید — فقط api.binobox.ir (یا همان آدرسی که در .env سرور دارید).

احراز هویت

در هر درخواست هدر Authorization را بگذارید. YOUR_API_KEY را با کلید کامل binox_sk_live_… جایگزین کنید.

برای POSTهای JSON هدر Content-Type: application/json لازم است.

کلید را در گیت یا فرانت‌اند عمومی قرار ندهید — فقط روی سرور خود نگه دارید.

الماس و هزینه

همان موجودی الماس داشبورد. قبل از اجرا موجودی چک می‌شود؛ بعد از موفقیت الماس کسر می‌شود. در پاسخ‌های موفق فیلد binobox را ببینید.

فیلد binobox در پاسخ

در پاسخ‌های موفق (چت، تصویر، صدا، …) این شیء برگردانده می‌شود:

"binobox": {
  "diamonds_charged": 0.18,
  "balance_remaining": 970.34
}

جدول endpointها

مصرف و آمار (GET /usage)

بدون scope خاص؛ فقط با کلید معتبر:

• request_count — تعداد کل درخواست‌های ثبت‌شده با این کلید
• success_count / error_count — موفق و ناموفق
• diamonds_charged — مجموع الماس کسرشده + balance_remaining موجودی لحظه‌ای

محدوده دسترسی (Scope)

هنگام ساخت کلید فقط chat / image / audio / music / video لازم را فعال کنید. مدل باید در GET /models باشد و capability با scope بخواند.

شیء settings (رسانه)

در تصویر/صدا/موزیک/ویدیو فیلد اختیاری settings همان پارامترهای استودیو است: numberOfImages، duration (ثانیه)، voice، aspectRatio و … بسته به مدل.

ویدیو (غیرهمزمان)

POST /videos/generations بلافاصله job می‌سازد (status: pending) و poll_url برمی‌گرداند. هر ۵–۱۰ ثانیه GET /jobs/:id را صدا بزنید تا status به completed یا failed برسد. الماس پس از اتمام موفق کسر می‌شود. job دیگران همیشه 404 برمی‌گرداند.

محدودیت نرخ

پیش‌فرض حدود ۶۰ درخواست در دقیقه به ازای هر کلید (429). برای ویدیو تعداد jobهای pending هم محدود است.

نمونه درخواست و پاسخ

YOUR_API_KEY را عوض کنید. model را از GET /models بردارید.

curl -sS https://api.binobox.ir/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gemini-3.1-flash-lite",
      "object": "model",
      "owned_by": "Google",
      "capabilities": ["chat"],
      "min_cost_diamonds": 0.18
    }
  ]
}

curl -sS https://api.binobox.ir/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "object": "usage",
  "period_days": 30,
  "request_count": 42,
  "success_count": 40,
  "error_count": 2,
  "diamonds_charged": 15.5,
  "balance_remaining": 970.34
}

curl -sS https://api.binobox.ir/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-lite",
    "messages": [{"role": "user", "content": "سلام"}],
    "max_tokens": 256,
    "temperature": 0.7
  }'

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "gemini-3.1-flash-lite",
  "choices": [{
    "message": { "role": "assistant", "content": "سلام!" },
    "finish_reason": "stop"
  }],
  "usage": { "total_tokens": 12 },
  "binobox": {
    "diamonds_charged": 0.18,
    "balance_remaining": 970.16
  }
}

curl -sS https://api.binobox.ir/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4-fast-generate",
    "prompt": "A minimal logo for a tech startup",
    "settings": { "numberOfImages": 1 }
  }'

{
  "created": 1780350000,
  "data": [{ "b64_json": "<base64>", "mime_type": "image/png" }],
  "binobox": { "diamonds_charged": 20, "balance_remaining": 950.16 }
}

curl -sS https://api.binobox.ir/api/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-tts",
    "input": "سلام، این یک تست است.",
    "settings": { "voice": "default" }
  }'

{
  "object": "audio.speech",
  "model": "gemini-3.1-flash-tts",
  "data": [{ "b64_json": "<base64>", "mime_type": "audio/mpeg" }],
  "binobox": { "diamonds_charged": 8, "balance_remaining": 942.16 }
}

curl -sS https://api.binobox.ir/api/v1/audio/music \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3-clip",
    "prompt": "Calm ambient background music, 30 seconds",
    "settings": { "duration": 30 }
  }'

{
  "object": "audio.music",
  "model": "lyria-3-clip",
  "duration": 30,
  "data": [{ "b64_json": "<base64>", "mime_type": "audio/mpeg" }],
  "binobox": { "diamonds_charged": 60, "balance_remaining": 882.16 }
}

curl -sS https://api.binobox.ir/api/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3-lite-generate",
    "prompt": "A cat walking in a sunny garden",
    "settings": { "duration": 4 }
  }'

{
  "object": "video.generation",
  "id": "job-uuid",
  "status": "pending",
  "model": "veo-3-lite-generate",
  "estimated_cost_diamonds": 800,
  "poll_url": "/api/v1/jobs/job-uuid",
  "binobox": { "diamonds_charged": 0, "balance_remaining": 882.16 }
}

curl -sS https://api.binobox.ir/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "object": "generation.job",
  "id": "job-uuid",
  "type": "video",
  "status": "completed",
  "model": "veo-3-lite-generate",
  "output": { "url": "https://api.binobox.ir/…" },
  "binobox": { "diamonds_charged": 800, "balance_remaining": 802.16 }
}

خطاها

بدنهٔ خطا معمولاً این شکل است:

{
  "error": {
    "message": "Insufficient diamond balance",
    "type": "api_error",
    "code": "INSUFFICIENT_BALANCE"
  }
}

• 401 — کلید نامعتبر، حذف‌شده یا ارسال نشده
• 402 — الماس کافی نیست (INSUFFICIENT_BALANCE)
• 403 — scope یا مدل مجاز نیست
• 400 — پارامتر ناقص (مثلاً model / prompt / messages)
• 404 — job پیدا نشد یا متعلق به شما نیست (JOB_NOT_FOUND)
• 429 — محدودیت درخواست در دقیقه
• 429 — تعداد job ویدیوی در صف زیاد (VIDEO_JOB_LIMIT)
• 502 — خطای سرویس‌دهندهٔ مدل (PROVIDER_ERROR)
• 503 — API عمومی روی سرور غیرفعال است