مستندات APIمسیرهاAsync tasks

پیگیری وضعیت تسک

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

نسخهٔ API: v1

پیگیری یک تسک

GEThttps://bananaai.ir/api/v1/tasks/:id

پارامتر مسیر همان مقدار فیلد id در پاسخ ایجاد تسک است. فقط تسک‌های همان حساب قابل خواندن‌اند؛ شناسهٔ ناشناخته یا متعلق به حساب دیگر 404 با کد task_not_found برمی‌گرداند.

bash

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

ساختار تسک

مسیر پیگیری و مسیر فهرست، هر دو همین ساختار را برمی‌گردانند:

JSON

1{
2  "id": "task_abc123",
3  "status": "completed",
4  "type": "video",
5  "model": "seedance-2",
6  "prompt": "A cinematic drone shot...",
7  "images": [],
8  "videos": ["https://cdn.bananaai.ir/.../output.mp4"],
9  "audios": [],
10  "error": null,
11  "credits_reserved": 250,
12  "credits_deducted": true,
13  "metadata": { "order_id": "1042" },
14  "created_at": "2026-07-11T12:00:00.000Z",
15  "completed_at": "2026-07-11T12:01:20.000Z"
16}

idstring: شناسهٔ تسک.
statusstring: وضعیت فعلی؛ جدول وضعیت‌ها را ببینید.; مقادیر مجاز:pendingprocessingcompletedfailed
typestring: نوع خروجی.; مقادیر مجاز:imagevideoaudio
modelstring | null: شناسهٔ مدلی که تسک با آن ساخته شده.
promptstring: پرامپت ارسالی.
imagesstring[]: نشانی عکس‌های خروجی؛ فقط پس از completed پر می‌شود.
videosstring[]: نشانی ویدیوهای خروجی؛ فقط پس از completed پر می‌شود.
audiosstring[]: نشانی فایل‌های صوتی: خروجی متن به گفتار و دوبلهٔ صوتی، و در تسک‌های گفتار به متن نشانی فایل ورودی (متن در prompt است).
errorstring | null: پیام خطا در حالت failed، در غیر این صورت null.
credits_reservedinteger: اعتبار رزروشده برای این تسک.
credits_deductedboolean: آیا اعتبار به‌طور قطعی کسر شده است (پس از موفقیت).
metadataobject: همان جفت‌های کلید/مقداری که هنگام ساخت تسک در فیلد metadata فرستادید (مقدارها رشته‌ای). اگر چیزی نفرستاده باشید {} است. در وب‌هوک هم برمی‌گردد.
created_atstring: زمان ثبت به قالب ISO 8601.
completed_atstring | null: زمان پایان پردازش (موفق یا ناموفق)، یا null.

وضعیت‌ها

وضعیت	معنی	اقدام شما
pending	تسک ثبت شده و در صف پردازش است. اعتبار رزرو شده اما کسر نشده.	ادامهٔ پیگیری
processing	مدل در حال تولید خروجی است.	ادامهٔ پیگیری
completed	خروجی آماده است؛ نشانی‌ها در images، videos یا audios. اعتبار کسر شده (credits_deducted: true).	دانلود خروجی و توقف پیگیری
failed	تولید ناموفق بود و دلیل در فیلد error ثبت شده. اعتبار رزروشده آزاد شده است.	بررسی error و توقف پیگیری

نکته

اگر پردازش بیش از حدود ۱۵ دقیقه طول بکشد، تسک به‌طور خودکار failed می‌شود و اعتبار رزروشده آزاد می‌شود. برای تسک‌های ناموفق هیچ اعتباری کسر نمی‌شود.

الگوی پیگیری

هر ۳ تا ۵ ثانیه یک‌بار مسیر پیگیری را بخوانید تا وضعیت به completed یا failed برسد. پیگیری از سهمیهٔ نرخ درخواست شما استفاده می‌کند؛ اگر 429 گرفتید، به اندازهٔ هدر Retry-After صبر کنید. تابع زیر همهٔ این‌ها را انجام می‌دهد:

JavaScript

const BASE = "https://bananaai.ir";
const headers = { Authorization: "Bearer ba_live_your_api_key" };

async function waitForTask(id, { intervalMs = 3000, timeoutMs = 15 * 60_000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/v1/tasks/${id}`, { headers });

    if (res.status === 429) {
      // سهمیهٔ درخواست تمام شده؛ به اندازهٔ Retry-After صبر کنید
      const retryAfter = Number(res.headers.get("Retry-After") ?? 5);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    const task = await res.json();
    if (task.status === "completed" || task.status === "failed") return task;

    await new Promise((r) => setTimeout(r, intervalMs));
  }

  throw new Error("Timed out waiting for task " + id);
}

const task = await waitForTask("task_abc123");
if (task.status === "completed") console.log(task.videos);
else console.error(task.error);

پس از قطع اتصال، درخواست تولید را تکرار نکنید

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

فهرست تسک‌ها

GEThttps://bananaai.ir/api/v1/tasks

فقط تسک‌هایی را برمی‌گرداند که با API ساخته شده‌اند (نه درخواست‌های استودیو)، به ترتیب از جدید به قدیم. برای صفحهٔ بعد، id آخرین آیتم را در starting_after بفرستید تا وقتی has_more برابر false شود.

پارامترهای query string (همه اختیاری):

limitintegerاختیاری: تعداد آیتم در هر صفحه، بین ۱ تا ۱۰۰.; پیش‌فرض:20
statusstringاختیاری: فیلتر بر اساس وضعیت.; مقادیر مجاز:pendingprocessingcompletedfailed
typestringاختیاری: فیلتر بر اساس نوع خروجی.; مقادیر مجاز:imagevideoaudio
created_afterstringاختیاری: فقط تسک‌های ساخته‌شده پس از این زمان (ISO 8601).; مثال:2026-08-11T00:00:00.000Z
created_beforestringاختیاری: فقط تسک‌های ساخته‌شده پیش از این زمان (ISO 8601).
starting_afterstringاختیاری: id آخرین آیتم صفحهٔ قبل برای صفحه‌بندی.; مثال:task_abc123

bash

curl "https://bananaai.ir/api/v1/tasks?limit=20&type=video&created_after=2026-08-11T00:00:00.000Z" \
  -H "Authorization: Bearer ba_live_your_api_key"

JSON

1{
2  "data": [
3    {
4      "id": "task_abc123",
5      "status": "completed",
6      "type": "video",
7      "model": "grok-imagine-video",
8      "prompt": "...",
9      "images": [],
10      "videos": ["https://cdn.bananaai.ir/.../output.mp4"],
11      "error": null,
12      "credits_reserved": 144,
13      "credits_deducted": true,
14      "created_at": "2026-08-11T07:34:26.000Z",
15      "completed_at": "2026-08-11T07:36:01.000Z"
16    }
17  ],
18  "has_more": true
19}