رفتن به محتوای اصلی
بنانا AI

ساخت و استفاده از کلید API

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

کلید را با ساختار زیر در هدر Authorization بفرستید:

bash
Authorization: Bearer ba_live_your_api_key

ساختار کلید

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

هشدار

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

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

در مسیرهای تولید عکس و ویدیو می‌توانید هدر Idempotency-Key را بفرستید. اگر پاسخی دریافت نکردید و همان درخواست را دوباره ارسال کردید، وظیفه جدیدی ساخته نمی‌شود و همان id قبلی برمی‌گردد.

bash
curl -X POST "https://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.

نکات امنیتی

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

اطلاعات

برای اتصال Cursor، Claude Code، Codex و سایر کلاینت‌های MCP به API، صفحه اتصال MCP را ببینید.
ساخت و استفاده از کلید API