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

# Seedance 视频：查询任务

> 按任务 id 查询 Seedance 视频的生成状态，完成后返回成片链接和实际用量。

用[创建任务](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/create.md)返回的 `id` 查询任务状态，完成后返回成片链接和用量。响应的格式与火山方舟「查询视频生成任务」接口相同。

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --url "https://code.heihuzi.ai/api/v3/contents/generations/tasks/$TASK_ID" \
  --header "Authorization: Bearer $HEIHUZI_API_KEY"
```

运行前把环境变量 `TASK_ID` 设为创建任务返回的 `id`。

## 路径参数

**id** `string` *required*

创建任务返回的 `id`，形如 `cgt-` 开头。同一账号下绑定「Seedance 视频」分组的任意 Key 都能查询；查不到时返回 404 `ResourceNotFound`。

## 状态

| `status` | 含义 | 费用 |
| - | - | - |
| `queued` | 排队中 | 余额保持冻结 |
| `running` | 生成中 | 余额保持冻结 |
| `succeeded` | 已完成，`content.video_url` 为成片链接 | 按实际用量扣费，多冻结的退回 |
| `failed` | 失败，`error` 里有原因 | 全额退回 |
| `expired` | 超过执行期限仍未完成 | 全额退回 |
| `cancelled` | 排队中被取消 | 全额退回 |

建议每 10 秒左右查询一次。即使不查询，任务结束后也会自动结算。

## 响应

```json theme={null}
{"id":"cgt-20261005170037-c27t7","model":"doubao-seedance-2-0-260128","status":"succeeded","content":{"video_url":"https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/…"},"usage":{"completion_tokens":50638,"total_tokens":50638},"created_at":1791190838,"updated_at":1791190988,"seed":67171,"resolution":"480p","ratio":"16:9","duration":5,"framespersecond":24,"service_tier":"default","execution_expires_after":172800,"generate_audio":true,"draft":false,"priority":0,"output_format":"mp4"}
```

* `usage.completion_tokens` 是本次的计费用量（token），计费规则见[创建任务](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/create.md)。
* `resolution`、`duration` 为实际出片的清晰度和时长。
* `content.video_url` 是成片链接，**24 小时内有效**，请及时下载保存。

## 错误响应

| HTTP | `error.code` | 说明 |
| - | - | - |
| 403 | `PermissionDenied` | Key 没有绑定「Seedance 视频」分组 |
| 404 | `ResourceNotFound` | 任务不存在、不属于你，或已被[删除](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/delete.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.