> ## 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.

# 查询视频生成任务

查询异步视频生成任务的状态、结果和用量信息。

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

`id` 为 [创建视频生成任务](/api/videos/create-task) 返回的任务 ID，通常以 `vidtask_` 开头。

<Warning>
  不要高频轮询。建议间隔 5 到 10 秒，最短不低于 3 秒。视频生成通常需要 30 秒至数分钟。
</Warning>

## 示例

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

## 响应字段

| 字段                             | 类型             | 说明                           |
| ------------------------------ | -------------- | ---------------------------- |
| `id`                           | string         | 平台任务 ID。                     |
| `object`                       | string         | 固定为 `video.generation.task`。 |
| `created`                      | integer        | 任务创建时间，Unix 秒。               |
| `created_at`                   | integer        | 任务创建时间，通常与 `created` 一致。     |
| `updated_at`                   | integer        | 最近更新时间，Unix 秒。               |
| `model`                        | string         | 视频模型名称。                      |
| `status`                       | string         | 任务状态。                        |
| `billing_status`               | string         | 账务状态。                        |
| `content.video_url`            | string         | 成功时返回的视频 URL。请及时下载转存。        |
| `content.video_url_expires_at` | string         | 视频 URL 过期时间，RFC3339 格式。      |
| `error.code`                   | string         | 失败原因码。                       |
| `error.message`                | string         | 失败原因说明。                      |
| `usage.completion_tokens`      | integer        | 输出 token 数。                  |
| `usage.total_tokens`           | integer        | 总 token 数。                   |
| `seed`                         | integer        | 随机种子。                        |
| `resolution`                   | string         | 实际生成分辨率。                     |
| `ratio`                        | string         | 实际生成宽高比。                     |
| `duration`                     | integer/string | 实际生成时长。                      |
| `frames`                       | integer        | 生成帧数。                        |
| `framespersecond`              | integer        | 生成帧率。                        |
| `generate_audio`               | boolean        | 是否包含同步音频。                    |
| `service_tier`                 | string         | 任务服务等级。                      |

## 任务状态

| `status`    | 说明  | 下一步                        |
| ----------- | --- | -------------------------- |
| `queued`    | 排队中 | 继续轮询                       |
| `running`   | 生成中 | 继续轮询                       |
| `succeeded` | 成功  | 读取 `content.video_url` 并下载 |
| `failed`    | 失败  | 查看 `error` 字段              |
| `cancelled` | 已取消 | 无需处理                       |
| `expired`   | 已超时 | 重新提交任务                     |

## 账务状态

| `billing_status` | 说明      |
| ---------------- | ------- |
| `frozen`         | 已冻结预估费用 |
| `settling`       | 结算处理中   |
| `settled`        | 已结算成功   |
| `refunded`       | 已退款     |
| `settle_failed`  | 结算失败    |
| `refund_failed`  | 退款失败    |

## 响应示例

```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."
  }
}
```

## 错误码

| HTTP 状态码 | `error.type`      | 场景                   |
| -------- | ----------------- | -------------------- |
| 404      | `task_not_found`  | 任务不存在，或不属于当前 API Key |
| 401      | `invalid_api_key` | API Key 缺失或无效        |