# پیگیری وضعیت


## پیگیری یک 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