معرفی API بنانا AI

معرفی

API بنانا AI یک رابط REST ساده برای تولید محتوای تصویری است. می‌توانید از متن، عکس یا ویدیو بسازید، عکس‌های موجود را ویرایش کنید و عکس را به ویدیو تبدیل کنید. هر درخواست یک شناسه دارد که با آن می‌توانید وضعیت پردازش و نتیجه را پیگیری کنید. مدل‌های در دسترس شامل Seedance، Grok Imagine، Gemini Omni، Kling و Veo 3.1 هستند. همه مسیرها نسخه‌بندی شده‌اند و با پیشوند /api/v1 در دسترس قرار دارند.

شروع سریع

ابتدا در پنل توسعه‌دهندگان یک کلید API بسازید. سپس آن را در هدر Authorization هر درخواست ارسال کنید:

Authorization: Bearer ba_live_your_api_key

نشانی پایه API: https://bananaai.ir

محدودیت تعداد درخواست‌ها

تعداد درخواست‌های هر کلید API در یک بازهٔ شناور ۶۰ ثانیه‌ای محدود است. همهٔ مسیرهای /api/v1، از جمله مسیر پیگیری وضعیت، از همین سهمیه استفاده می‌کنند. سقف مجاز به پلن فعال حساب شما بستگی دارد:

اگر از حد مجاز عبور کنید، API پاسخ 429 با کد rate_limit_exceeded برمی‌گرداند. در این حالت اعتباری از حساب شما کسر نمی‌شود. هدر Retry-After تعداد ثانیه‌های لازم تا ارسال دوباره درخواست را نشان می‌دهد. برای جزئیات بیشتر به بخش خطاها و پیام‌ها.

روند پردازش درخواست

1. 1

   ارسال درخواست

   درخواست تولید عکس یا ویدیو را به مسیر مربوط بفرستید.
2. 2

   دریافت شناسه درخواست

   مقدار فیلد id را از پاسخ JSON بخوانید و برای پیگیری وضعیت نگه دارید. نام این فیلد taskId یا task_id نیست.
3. 3

   بررسی وضعیت

   هر ۳ تا ۵ ثانیه مسیر GET /api/v1/tasks/:id را بررسی کنید تا مقدار status به completed یا failed تغییر کند.
4. 4

   دریافت نتیجه

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

یکپارچه‌سازی مطمئن

• شناسه درخواست همیشه در فیلد id برگردانده می‌شود. مقدار task.id را از پاسخ بخوانید. پاسخ JSON شامل فیلدهای taskId یا task_id نیست.
• برای پیگیری وضعیت، مقدار id را در مسیر GET /api/v1/tasks/:id قرار دهید. این مسیر را هر ۳ تا ۵ ثانیه بررسی کنید تا وضعیت به completed یا failed تغییر کند.
• اگر مهلت انتظار کلاینت تمام شد یا اتصال قطع شد، درخواست تولید را بدون بررسی دوباره ارسال نکنید. ممکن است درخواست نخست با موفقیت ثبت شده باشد. با استفاده از Idempotency-Key می‌توانید همان درخواست را بدون خطر ایجاد نمونه تکراری دوباره ارسال کنید. اگر id را دریافت کرده‌اید، فقط وضعیت همان درخواست را پیگیری کنید.
• پردازش درخواست‌ها ناهمگام است و ممکن است چند دقیقه طول بکشد. تمام شدن مهلت انتظار یک درخواست POST لزوماً به‌معنای شکست عملیات نیست. وضعیت ثبت‌شده برای درخواست، نتیجه نهایی را مشخص می‌کند.