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

# 获取任务状态

> 查询统一视频任务接口的执行进度与结果，并了解对应的 OpenAI 视频兼容查询路径。

# 获取任务状态

这个接口用于查询通过统一视频任务入口提交的异步任务状态。返回结构使用 `code`、`message`、`data` 包装。

* 查询的是平台公开 `task_id`，不是上游真实任务 ID。
* 成功响应固定返回 `code = success`。
* 适合与 `/v1/video/generations` 搭配使用。
* 同一任务也可能通过 `/v1/videos/{task_id}` 以 OpenAI `video` 对象格式查询。

## 方法与路径

```http theme={null}
GET /v1/video/generations/{task_id}
```

## 请求示例

<CodeGroup>
  ```bash theme={null}
  curl https://www.token-nova.com/v1/video/generations/task-video-abc123 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python theme={null}
  import requests

  resp = requests.get(
      "https://www.token-nova.com/v1/video/generations/task-video-abc123",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      timeout=30,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch(
    "https://www.token-nova.com/v1/video/generations/task-video-abc123",
    {
      headers: { Authorization: "Bearer YOUR_API_KEY" },
    }
  );

  console.log(await response.json());
  ```
</CodeGroup>

## 响应示例

<ResponseExample>
  ```json 200 - 排队中 theme={null}
  {
    "code": "success",
    "message": "",
    "data": {
      "task_id": "task-video-abc123",
      "status": "queued",
      "url": "",
      "format": "mp4",
      "metadata": null,
      "error": null
    }
  }
  ```

  ```json 200 - 已完成 theme={null}
  {
    "code": "success",
    "message": "",
    "data": {
      "task_id": "task-video-abc123",
      "status": "succeeded",
      "url": "https://...",
      "format": "mp4",
      "metadata": {
        "duration": 5,
        "width": 1280,
        "height": 720,
        "fps": 24
      },
      "error": null
    }
  }
  ```

  ```json 200 - 任务失败 theme={null}
  {
    "code": "success",
    "message": "",
    "data": {
      "task_id": "task-video-abc123",
      "status": "failed",
      "url": "",
      "format": "mp4",
      "metadata": null,
      "error": {
        "code": "content_policy",
        "message": "Content policy violation"
      }
    }
  }
  ```

  ```json 400 theme={null}
  {
    "code": "task_not_exist",
    "message": "task_not_exist",
    "data": null
  }
  ```

  ```json 401 theme={null}
  {
    "code": "invalid_api_key",
    "message": "无效的令牌",
    "data": null
  }
  ```
</ResponseExample>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField body="task_id" type="string" required>
  统一视频任务入口返回的公开任务 ID。
</ParamField>

## Response

<ResponseField name="code" type="string">
  业务状态码。成功时固定为 `success`。
</ResponseField>

<ResponseField name="message" type="string">
  错误或补充信息。成功时通常为空字符串。
</ResponseField>

<ResponseField name="data.task_id" type="string">
  任务 ID。
</ResponseField>

<ResponseField name="data.status" type="string">
  任务状态。常见值为 `queued`、`processing`、`succeeded`、`failed`。
</ResponseField>

<ResponseField name="data.url" type="string">
  最终视频结果地址。部分渠道会返回平台代理地址。
</ResponseField>

<ResponseField name="data.error" type="object">
  失败任务的错误详情。
</ResponseField>

## 使用场景

### 轮询直到完成

建议每 `5` 到 `10` 秒轮询一次，直到 `status` 变为 `succeeded` 或 `failed`。

### 切换到 OpenAI 查询结构

如果客户端已经按 OpenAI `video` 对象解析结果，可以直接改查：

```bash theme={null}
curl https://www.token-nova.com/v1/videos/task-video-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## 注意事项

<Info>
  `/v1/video/generations/{task_id}` 和 `/v1/videos/{task_id}` 查询的是同一类视频任务，但返回结构不同。前者是统一任务包装，后者是 OpenAI 视频对象。
</Info>

## 相关接口

* [统一视频生成接口](../videos/video-generations)
* [OpenAI 视频兼容接口](../videos/openai-videos)