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

# Get Task Status

> Query the execution progress and result of the unified video task interface, and learn the corresponding OpenAI video-compatible query path.

# Get Task Status

This endpoint is used to query the status of asynchronous tasks submitted through the unified video task entry point. The returned structure is wrapped with `code`, `message`, and `data`.

* The query targets the platform-exposed `task_id`, not the upstream real task ID.
* A successful response always returns `code = success`.
* Suitable for use together with `/v1/video/generations`.
* The same task can also be queried via `/v1/videos/{task_id}` in the OpenAI `video` object format.

## Method and Path

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

## Request Example

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

## Response Example

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

  ```json 200 - Completed 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 - Task Failed 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": "Invalid token",
    "data": null
  }
  ```
</ResponseExample>

## Authentication

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

## Path Parameters

<ParamField body="task_id" type="string" required>
  The public task ID returned by the unified video task entry point.
</ParamField>

## Response

<ResponseField name="code" type="string">
  Business status code. Fixed as `success` on success.
</ResponseField>

<ResponseField name="message" type="string">
  Error or supplementary information. Usually an empty string on success.
</ResponseField>

<ResponseField name="data.task_id" type="string">
  Task ID.
</ResponseField>

<ResponseField name="data.status" type="string">
  Task status. Common values are `queued`, `processing`, `succeeded`, and `failed`.
</ResponseField>

<ResponseField name="data.url" type="string">
  Final video result URL. Some channels may return a platform proxy URL.
</ResponseField>

<ResponseField name="data.error" type="object">
  Error details for failed tasks.
</ResponseField>

## Use Cases

### Poll Until Completion

It is recommended to poll every `5` to `10` seconds until `status` becomes `succeeded` or `failed`.

### Switch to the OpenAI Query Structure

If the client is already parsing results according to the OpenAI `video` object, you can directly query:

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

## Notes

<Info>
  `/v1/video/generations/{task_id}` and `/v1/videos/{task_id}` query the same type of video task, but return different structures. The former is a unified task wrapper, while the latter is an OpenAI video object.
</Info>

## Related APIs

* [Unified Video Generation API](../videos/video-generations)
* [OpenAI Video-Compatible API](../videos/openai-videos)