احراز هویت

ساخت کلید

1. 1

   وارد پنل توسعه‌دهندگان شوید

   از پنل توسعه‌دهندگان روی «ساخت کلید جدید» بزنید. دسترسی به API برای پلن کاوشگر و بالاتر فعال است؛ حساب رایگان خطای plan_required می‌گیرد.
2. 2

   کلید را همان لحظه ذخیره کنید

   کلید کامل فقط هنگام ساخت نمایش داده می‌شود. آن را در یک متغیر محیطی یا مخزن رمز امن نگه دارید.
3. 3

   برای هر محیط یک کلید بسازید

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

هدر Authorization

کلید را با طرح Bearer در هدر Authorization هر درخواست بفرستید. نبود هدر خطای 401 با کد missing_authorization برمی‌گرداند.

Authorization: Bearer ba_live_your_api_key

curl "https://bananaai.ir/api/v1/account" \
  -H "Authorization: Bearer ba_live_your_api_key"

ساختار کلید

کلیدهای API با پیشوند ba_live_ شروع می‌شوند و پس از آن یک رشتهٔ تصادفی می‌آید. سرور فقط هش کلید را نگه می‌دارد؛ اگر کلید را گم کنید باید کلید جدیدی بسازید.

• هر کلید به حساب کاربری شما متصل است و از اعتبار همان حساب استفاده می‌کند.
• لغو کلید بلافاصله اعمال می‌شود و درخواست‌های بعدی با 403 و کد revoked_api_key رد می‌شوند.
• سقف نرخ درخواست به ازای هر کلید محاسبه می‌شود، نه به ازای حساب.

Idempotency-Key

در مسیرهای تولید عکس و ویدیو می‌توانید هدر اختیاری Idempotency-Key را بفرستید. اگر پاسخ را دریافت نکردید (مثلاً به‌خاطر قطع شبکه) و همان درخواست را دوباره فرستادید، تسک دومی ساخته نمی‌شود و همان id قبلی برمی‌گردد. برای هر عملیات منطقی یک مقدار یکتا (مثلاً UUID یا شناسهٔ سفارش) انتخاب کنید.

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": "Slow cinematic orbit around the product",
    "image_urls": ["https://example.com/a.jpg"]
  }'

• مقدار باید ۱ تا ۲۵۶ کاراکتر ASCII چاپ‌پذیر و بدون فاصله باشد.
• مسیرهای پشتیبانی‌شده: /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 را تغییر نمی‌دهد.

نکات امنیتی

• درخواست‌ها را از سرور خودتان بفرستید و کلید را با یک متغیر محیطی (مثلاً BANANAAI_API_KEY) به برنامه بدهید.
• اگر کاربران نهایی شما باید محتوا تولید کنند، یک مسیر واسط در بک‌اند خود بسازید که با کلید شما به API بنانا وصل می‌شود.
• پاسخ‌های خطا را لاگ کنید اما هدر Authorization را از لاگ‌ها حذف کنید.
• کلیدهای بدون استفاده را از پنل لغو کنید تا سطح حمله کوچک بماند.