احراز هویت

برای استفاده از API، هر درخواست باید همراه با یک کلید API معتبر ارسال شود.

هدر Authorization

Authorization: Bearer ba_live_your_api_key

ساختار کلید

کلیدهای API با ba_live_ شروع می‌شوند. کلید کامل فقط همان لحظه ساخت نمایش داده می‌شود، پس آن را در جای امن نگه دارید.

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

Idempotency-Key (اختیاری)

برای endpointهای ساخت (عکس/ویدیو) می‌توانید هدر Idempotency-Key بفرستید تا اگر پاسخ را نگرفتید و دوباره همان درخواست را زدید، task دوم ساخته نشود و همان id قبلی برگردد.

curl -X POST "https://api.bananaai.ir/api/v1/videos/image-to-video" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Idempotency-Key: order-42-video-1" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video","prompt":"...","image_urls":["https://example.com/a.jpg"]}'

قوانین:

• هدر اختیاری است؛ بدون آن رفتار API مثل قبل است.
• مقدار باید ۱ تا ۲۵۶ کاراکتر ASCII قابل چاپ باشد (بدون فاصله).
• برای هر عملیات منطقی یکتا باشد (مثلاً UUID یا شناسه سفارش شما).
• همان کلید + همان بدنه، در صورت موفقیت تا ۲۴ ساعت همان پاسخ را برمی‌گرداند (هدر Idempotent-Replayed: true).
• همان کلید با بدنهٔ متفاوت: HTTP 422 با کد idempotency_key_reused.
• اگر درخواست اول هنوز در حال اجراست: HTTP 409 با کد idempotency_key_in_progress و هدر Retry-After.

روی این مسیرها پشتیبانی می‌شود: /api/v1/images/generations، /api/v1/images/edits، /api/v1/videos/generations، /api/v1/videos/image-to-video، /api/v1/audio/speech، /api/v1/audio/transcriptions، /api/v1/audio/dubbing و /api/v1/chat/completions (فقط بدون stream).

نکات امنیتی

• اگر کلیدی را لغو کنید، همان لحظه غیرفعال می‌شود.
• هر کلید به حساب کاربری شما وصل است و از اعتبار همان حساب استفاده می‌کند.
• بهتر است برای محیط توسعه و محیط اصلی، کلیدهای جداگانه بسازید.