مسیرها

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

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

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

نسخهٔ .md

پیگیری یک task

GET https://api.bananaai.ir/api/v1/tasks/:id

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

نمونه curl

bash

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

فهرست taskها

GET https://api.bananaai.ir/api/v1/tasks

فقط taskهای ساخته‌شده با API. برای صفحه بعد، id آخرین آیتم را در starting_after بفرستید.

Query params:

limit (optional, 1-100, default 20)
status (optional): pending | processing | completed | failed
type (optional): image | video | audio
created_after / created_before (optional, ISO 8601)
starting_after (optional): task id از صفحه قبل

نمونه curl

bash

curl "https://api.bananaai.ir/api/v1/tasks?limit=20&type=video" \
  -H "Authorization: Bearer ba_live_your_api_key"

نمونه پاسخ فهرست

json

{
  "data": [
    {
      "id": "task_abc123",
      "status": "completed",
      "type": "video",
      "model": "grok-imagine-video",
      "prompt": "...",
      "images": [],
      "videos": ["https://cdn.example.com/out.mp4"],
      "error": null,
      "credits_reserved": 144,
      "credits_deducted": true,
      "created_at": "2026-08-11T07:34:26.000Z",
      "completed_at": "2026-08-11T07:36:01.000Z"
    }
  ],
  "has_more": true
}

بررسی دوره‌ای

هر ۳ تا ۵ ثانیه تا رسیدن به completed یا failed (در حالت failed فیلد error را ببینید). برای retry امن بعد از timeout از Idempotency-Key استفاده کنید.

وضعیت‌ها

pending / processing: در صف یا در حال اجرا
completed: فیلد images، videos یا audios پر شده
failed: فیلد error تنظیم شده

نمونه پاسخ موفق یک task

json

{
  "id": "task_abc123",
  "status": "completed",
  "type": "video",
  "model": "seedance-2",
  "prompt": "...",
  "images": [],
  "videos": ["https://cdn.example.com/out.mp4"],
  "error": null,
  "credits_reserved": 250,
  "credits_deducted": true,
  "metadata": { "order_id": "1042" },
  "created_at": "2026-01-01T12:00:00.000Z",
  "completed_at": "2026-01-01T12:02:00.000Z"
}

اگر حدود ۱۵ دقیقه بگذرد و تمام نشود، task به failed می‌رود و اعتباری کسر نمی‌شود.

فیلد metadata: هر مسیر ساخت تسک یک metadata اختیاری (تا ۱۶ کلید، مقدار رشته تا ۵۰۰ کاراکتر) می‌پذیرد که در پاسخ تسک و وب‌هوک عیناً برمی‌گردد.

به‌جای polling می‌توانید وب‌هوک ثبت کنید: https://api.bananaai.ir/docs/webhooks