> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iviker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query video task

Query the status, output, and usage for an asynchronous video task.

```
GET /v1/videos/generations/{id}
Authorization: Bearer <API_KEY>
```

`id` is the task ID returned by [Create video task](/en/api/videos/create-task) and usually starts with `vidtask_`.

<Warning>
  Do not poll too frequently. Use a 5 to 10 second interval, with a minimum of 3 seconds. Video generation often takes 30 seconds to several minutes.
</Warning>

## Example

```bash theme={null}
curl "https://{your-domain}/v1/videos/generations/vidtask_3cb6299b32d24f93a82e8a74b3e06161" \
  -H "Authorization: Bearer $API_KEY"
```

## Response fields

| Field                          | Type           | Description                                     |
| ------------------------------ | -------------- | ----------------------------------------------- |
| `id`                           | string         | Platform task ID.                               |
| `object`                       | string         | Fixed to `video.generation.task`.               |
| `created`                      | integer        | Creation time in Unix seconds.                  |
| `created_at`                   | integer        | Creation time, usually the same as `created`.   |
| `updated_at`                   | integer        | Last update time in Unix seconds.               |
| `model`                        | string         | Video model name.                               |
| `status`                       | string         | Task status.                                    |
| `billing_status`               | string         | Billing status.                                 |
| `content.video_url`            | string         | Returned when successful. Download it promptly. |
| `content.video_url_expires_at` | string         | Video URL expiry time in RFC3339 format.        |
| `error.code`                   | string         | Failure code.                                   |
| `error.message`                | string         | Failure message.                                |
| `usage.completion_tokens`      | integer        | Output token count.                             |
| `usage.total_tokens`           | integer        | Total token count.                              |
| `seed`                         | integer        | Random seed.                                    |
| `resolution`                   | string         | Actual output resolution.                       |
| `ratio`                        | string         | Actual output aspect ratio.                     |
| `duration`                     | integer/string | Actual duration.                                |
| `frames`                       | integer        | Output frame count.                             |
| `framespersecond`              | integer        | Output frame rate.                              |
| `generate_audio`               | boolean        | Whether synced audio is included.               |
| `service_tier`                 | string         | Task service tier.                              |

## Status values

| `status`    | Meaning         | Next step                             |
| ----------- | --------------- | ------------------------------------- |
| `queued`    | In queue        | Keep polling                          |
| `running`   | Being generated | Keep polling                          |
| `succeeded` | Success         | Read `content.video_url` and download |
| `failed`    | Failed          | Check `error`                         |
| `cancelled` | Cancelled       | No action needed                      |
| `expired`   | Timed out       | Resubmit the task                     |

## Billing status

| `billing_status` | Meaning                  |
| ---------------- | ------------------------ |
| `frozen`         | Estimated cost is frozen |
| `settling`       | Settlement in progress   |
| `settled`        | Settlement succeeded     |
| `refunded`       | Refunded                 |
| `settle_failed`  | Settlement failed        |
| `refund_failed`  | Refund failed            |

## Response examples

```json theme={null}
{
  "id": "vidtask_3cb6299b32d24f93a82e8a74b3e06161",
  "object": "video.generation.task",
  "created": 1779782400,
  "created_at": 1779782400,
  "updated_at": 1779782488,
  "model": "dreamina-seedance-2-0",
  "status": "succeeded",
  "billing_status": "settled",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "generate_audio": true,
  "service_tier": "default",
  "content": {
    "video_url": "https://example.com/generated-video.mp4",
    "video_url_expires_at": "2026-05-27T12:00:00Z"
  },
  "usage": {
    "completion_tokens": 540900,
    "total_tokens": 540900
  }
}
```

```json theme={null}
{
  "id": "vidtask_3cb6299b32d24f93a82e8a74b3e06161",
  "object": "video.generation.task",
  "created": 1779782400,
  "created_at": 1779782400,
  "updated_at": 1779782488,
  "model": "dreamina-seedance-2-0",
  "status": "failed",
  "billing_status": "refunded",
  "error": {
    "code": "OutputVideoSensitiveContentDetected",
    "message": "The request failed because the output video may contain sensitive information."
  }
}
```

## Error codes

| HTTP status | `error.type`      | Scenario                                                          |
| ----------- | ----------------- | ----------------------------------------------------------------- |
| 404         | `task_not_found`  | The task does not exist or does not belong to the current API key |
| 401         | `invalid_api_key` | The API key is missing or invalid                                 |