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

API بنانا AI یک رابط REST ساده برای تولید محتوا است: از متن، عکس یا ویدیو بسازید، عکس‌های موجود را ویرایش کنید، عکس را به ویدیو تبدیل کنید، با مدل‌های زبانی (GPT 6 Astra، Claude، Grok، Gemini و …) گفتگو کنید و متن را به گفتار، گفتار را به متن یا صوت و ویدیو را به زبان دیگری دوبله کنید. درخواست‌های عکس، ویدیو و دوبله یک تسک ناهمگام می‌سازند که با شناسهٔ آن وضعیت پردازش و نتیجه را پیگیری می‌کنید؛ گفتگو، متن به گفتار و گفتار به متن همان لحظه پاسخ می‌دهند. اعتبار فقط زمانی کسر می‌شود که درخواست با موفقیت به پایان برسد.

شروع سریع

سه مرحله تا اولین خروجی: کلید بسازید، درخواست بفرستید و وضعیت تسک را پیگیری کنید. نمونهٔ زیر همین چرخه را به‌طور کامل نشان می‌دهد.

1. 1

   کلید API بسازید

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

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

   همهٔ مسیرها با همین هدر احراز هویت می‌شوند:

   HTTP

   کپی

   Authorization: Bearer ba_live_your_api_key

3. 3

   درخواست بدهید و نتیجه را بگیرید

   درخواست تولید یک شناسه (id) برمی‌گرداند. همان شناسه را هر ۳ تا ۵ ثانیه از GET /api/v1/tasks/:id بخوانید تا وضعیت به completed برسد:

   JavaScriptPython

   JavaScript

   کپی

   const BASE = "https://bananaai.ir";
   const headers = {
     Authorization: "Bearer ba_live_your_api_key",
     "Content-Type": "application/json",
   };
   
   // ۱) ثبت درخواست
   const created = await fetch(`${BASE}/api/v1/images/generations`, {
     method: "POST",
     headers,
     body: JSON.stringify({
       model: "nano-banana-2",
       prompt: "شهری آینده‌نگر در غروب",
       image_size: "9:16",
     }),
   }).then((r) => r.json());
   
   // ۲) پیگیری تا پایان پردازش (هر ۳ ثانیه)
   let task = created;
   while (task.status === "pending" || task.status === "processing") {
     await new Promise((resolve) => setTimeout(resolve, 3000));
     task = await fetch(`${BASE}/api/v1/tasks/${created.id}`, { headers })
       .then((r) => r.json());
   }
   
   // ۳) نتیجه
   if (task.status === "completed") {
     console.log(task.images); // ["https://..."]
   } else {
     console.error(task.error);
   }

مسیرها در یک نگاه

همهٔ مسیرها نسخه‌بندی شده‌اند و زیر /api/v1 قرار دارند. مسیرهای تولید عکس، ویدیو و دوبله یک تسک می‌سازند، مسیرهای گفتگو، متن به گفتار و گفتار به متن همان لحظه پاسخ می‌دهند؛ مسیرهای پیگیری، فهرست مدل‌ها و حساب فقط‌خواندنی‌اند و اعتباری مصرف نمی‌کنند.

مدل‌های در دسترس

همان مدل‌های استودیو و مغز بنانا در API هم در دسترس‌اند. شناسهٔ هر مدل را در فیلد model درخواست بفرستید؛ برای جزئیات هزینه روی مدل کلیک کنید. همین فهرست را می‌توانید با GET /api/v1/models به‌صورت برنامه‌نویسی بخوانید.

چرخهٔ عمر یک درخواست

تولید عکس و ویدیو زمان‌بر است؛ برای همین پاسخ POST فوراً برمی‌گردد و پردازش در پس‌زمینه ادامه می‌یابد. (مسیر گفتگو از این چرخه مستثناست و پاسخ نهایی را در همان درخواست برمی‌گرداند.) وضعیت تسک از این مسیر عبور می‌کند:

1. 1

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

   درخواست تولید عکس یا ویدیو را به مسیر مربوط بفرستید. در همین لحظه فقط کافی بودن اعتبار بررسی و مبلغ لازم رزرو می‌شود.
2. 2

   دریافت شناسهٔ تسک

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

   پیگیری وضعیت

   هر ۳ تا ۵ ثانیه GET /api/v1/tasks/:id را بخوانید تا status به completed یا failed برسد. پردازش ویدیو ممکن است چند دقیقه طول بکشد.
4. 4

   دریافت نتیجه

   پس از تکمیل موفق، نشانی خروجی‌ها در فیلد images یا videos قرار دارد و اعتبار رزروشده کسر می‌شود. اگر تسک ناموفق شود، اعتبار آزاد می‌شود و دلیل در error ثبت شده است.

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

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

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

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

• شناسهٔ تسک همیشه در فیلد id است. پاسخ JSON شامل taskId یا task_id نیست.
• اگر مهلت انتظار کلاینت تمام شد یا اتصال قطع شد، درخواست تولید را کورکورانه دوباره نفرستید؛ ممکن است تسک اول با موفقیت ثبت شده باشد. با هدر Idempotency-Key می‌توانید همان درخواست را بدون خطر ساخت نمونهٔ تکراری دوباره بفرستید.
• تمام شدن مهلت یک درخواست POST لزوماً به‌معنای شکست عملیات نیست. وضعیت ثبت‌شدهٔ تسک، نتیجهٔ نهایی را مشخص می‌کند.
• پیگیری زودتر از هر ۳ ثانیه فقط سهمیهٔ درخواست شما را سریع‌تر مصرف می‌کند و نتیجه را جلو نمی‌اندازد.