# 查询视频任务（OpenAI 兼容） > 查询以 OpenAI 兼容格式提交的视频任务状态与结果 > 状态取值：`SUCCESS`、`IN_PROGRESS`、`QUEUED`、`FAILURE` > 完成后从 `data.video_url` 取直链，或用下载接口经网关取回 `GET /v1/video/generations/{task_id}` ## 认证 - `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 Seedance 系列的接口需要在 [ark 站](https://ark.oairoute.com/) 单独获取 Key，与 api 站的 Key 不通用。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_ARK_KEY ``` ## 路径参数 - `task_id` (string / 必填) — 提交任务时返回的任务 ID。 ## 状态流转 ```text QUEUED -> IN_PROGRESS -> SUCCESS 成片可取 -> FAILURE 查看 fail_reason ``` - `QUEUED`：已受理，排队中 - `IN_PROGRESS`：生成中，`data.progress` 为百分比字符串，如 `50%` - `SUCCESS`：已完成，成片地址在 `data.video_url` - `FAILURE`：已失败，原因在 `data.fail_reason` 轮询节奏：每 5 秒一次，总超时约 10 分钟。多数 Seedance 任务在 1 到 3 分钟内完成。 ## 响应 外层是 `{ code, message, data }` 信封，任务对象在 `data` 里。 - `code` (string) — 固定为 `success`。 - `message` (string) — 通常为空字符串。 - `data.id` (integer) — 任务在库内的自增 ID。 - `data.task_id` (string) — 任务 ID，与请求路径里的值一致。 - `data.action` (string) — 任务类型，如 `text_to_video`、`image_to_video`。 - `data.status` (string) — 取值 `QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`。 - `data.fail_reason` (string) — 失败原因，成功时为空字符串。 - `data.result_url` (string) — 成片地址，成功后才有。 - `data.video_url` (string) — 与 `result_url` 同值的成片地址，给按 OpenAI 视频字段名解析的客户端使用。成功后才有。 - `data.last_frame_url` (string) — 末帧图片地址。上游产出末帧时才有，例如豆包在提交时把 `return_last_frame` 设为 `true`。 - `data.progress` (string) — 进度百分比字符串，如 `100%`。 - `data.submit_time` / `data.start_time` / `data.finish_time` (integer) — 提交、开始、结束时间，Unix 秒，未发生时为 0。 - `data.properties` (object) — 本次任务使用的模型信息，含 `input`、`origin_model_name`、`upstream_model_name`。 - `data.data` (object) — 上游返回的原始任务快照。不同渠道结构不同，例如豆包是 `{ id, model, status, content: { video_url, last_frame_url }, usage, ... }`。 ## 取回成片 `SUCCESS` 之后有两种取法： 1. 直接用 `data.video_url` 里的直链 2. 调 `GET /v1/videos/{task_id}/content` 经网关下载，需要鉴权，地址不外泄 ## 错误码 | HTTP | 含义 | |---|---| | 401 | Token 缺失或无效，type 为 authentication_error | 更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。 ## 使用示例 **排队中{Queued}::cURL** ``` curl --request GET \ --url https://ark.oairoute.com/v1/video/generations/task_abc123def456 \ --header 'Authorization: Bearer YOUR_ARK_KEY' ``` **排队中{Queued}::Python** ``` import requests url = "https://ark.oairoute.com/v1/video/generations/task_abc123def456" headers = {"Authorization": "Bearer YOUR_ARK_KEY"} res = requests.get(url, headers=headers) print(res.json()) ``` **排队中{Queued}::JavaScript** ``` const res = await fetch("https://ark.oairoute.com/v1/video/generations/task_abc123def456", { headers: { Authorization: "Bearer YOUR_ARK_KEY" }, }); console.log(await res.json()); ``` **200 排队中{Queued}** ``` { "code": "success", "message": "", "data": { "id": 229, "created_at": 1763088289, "updated_at": 1763088289, "task_id": "task_abc123def456", "action": "text_to_video", "status": "QUEUED", "fail_reason": "", "submit_time": 1763088289, "start_time": 0, "finish_time": 0, "progress": "20%", "properties": { "input": "", "origin_model_name": "seedance-2.5" }, "data": {} } } ``` **生成中{In progress}::cURL** ``` curl --request GET \ --url https://ark.oairoute.com/v1/video/generations/task_abc123def456 \ --header 'Authorization: Bearer YOUR_ARK_KEY' ``` **生成中{In progress}::Python** ``` import requests url = "https://ark.oairoute.com/v1/video/generations/task_abc123def456" headers = {"Authorization": "Bearer YOUR_ARK_KEY"} res = requests.get(url, headers=headers) print(res.json()) ``` **生成中{In progress}::JavaScript** ``` const res = await fetch("https://ark.oairoute.com/v1/video/generations/task_abc123def456", { headers: { Authorization: "Bearer YOUR_ARK_KEY" }, }); console.log(await res.json()); ``` **200 生成中{In progress}** ``` { "code": "success", "message": "", "data": { "id": 229, "created_at": 1763088289, "updated_at": 1763088300, "task_id": "task_abc123def456", "action": "text_to_video", "status": "IN_PROGRESS", "fail_reason": "", "submit_time": 1763088289, "start_time": 1763088295, "finish_time": 0, "progress": "50%", "properties": { "input": "", "origin_model_name": "seedance-2.5" }, "data": { "id": "cgt-20261104203557-7z0tq", "model": "doubao-seedance-2-5-260628", "status": "running" } } } ``` **已完成{Completed}::cURL** ``` curl --request GET \ --url https://ark.oairoute.com/v1/video/generations/task_abc123def456 \ --header 'Authorization: Bearer YOUR_ARK_KEY' ``` **已完成{Completed}::Python** ``` import requests url = "https://ark.oairoute.com/v1/video/generations/task_abc123def456" headers = {"Authorization": "Bearer YOUR_ARK_KEY"} res = requests.get(url, headers=headers) print(res.json()) ``` **已完成{Completed}::JavaScript** ``` const res = await fetch("https://ark.oairoute.com/v1/video/generations/task_abc123def456", { headers: { Authorization: "Bearer YOUR_ARK_KEY" }, }); console.log(await res.json()); ``` **200 已完成{Completed}** ``` { "code": "success", "message": "", "data": { "id": 229, "created_at": 1763088289, "updated_at": 1763088400, "task_id": "task_abc123def456", "action": "text_to_video", "status": "SUCCESS", "fail_reason": "", "result_url": "https://cdn.example.com/videos/output-abc123.mp4", "video_url": "https://cdn.example.com/videos/output-abc123.mp4", "last_frame_url": "https://cdn.example.com/videos/output-abc123_last-frame.png", "submit_time": 1763088289, "start_time": 1763088295, "finish_time": 1763088400, "progress": "100%", "properties": { "input": "", "origin_model_name": "seedance-2.5", "upstream_model_name": "doubao-seedance-2-5-260628" }, "data": { "id": "cgt-20261104203557-7z0tq", "model": "doubao-seedance-2-5-260628", "status": "succeeded", "content": { "video_url": "https://cdn.example.com/videos/output-abc123.mp4", "last_frame_url": "https://cdn.example.com/videos/output-abc123_last-frame.png" }, "seed": 42, "resolution": "1080p", "duration": 5, "ratio": "16:9", "usage": { "total_tokens": 108900, "completion_tokens": 108900 } } } } ```