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

# Truy xuất một video Seedance

> Thăm dò một tác vụ video Seedance theo id trên CometAPI bằng GET /v1/videos/{id}. Hoạt động với các tác vụ Seedance 1.0 Pro, 1.5 Pro và 2.0. Trả về trạng thái hiện tại, tiến độ và `video_url` đã ký sau khi tác vụ đạt completed.

Sử dụng endpoint này để đọc trạng thái của một tác vụ được tạo thông qua [Tạo một video Seedance](./create). `id` trong path là giá trị được trả về bởi lệnh gọi tạo, bất kể model Seedance nào đã tạo ra tác vụ.

Phần thân phản hồi chính là đối tượng tác vụ video. Đọc `status`, `progress` và `video_url` ở cấp cao nhất.

## Máy trạng thái

API trả về các chuỗi trạng thái viết thường. `queued` và `in_progress` là không kết thúc; `completed`, `failed` và `error` là kết thúc và tác vụ sẽ không thay đổi nữa.

| Status        | Ý nghĩa                                          | Kết thúc |
| ------------- | ------------------------------------------------ | -------- |
| `queued`      | Đã được chấp nhận và đưa vào hàng đợi để render. | không    |
| `in_progress` | Đang render.                                     | không    |
| `completed`   | Đã hoàn tất. `video_url` có trong phản hồi.      | có       |
| `failed`      | Nhà cung cấp đã từ chối tác vụ.                  | có       |
| `error`       | Lỗi nội bộ đã ngăn quá trình hoàn tất.           | có       |

## Nhịp độ thăm dò

Thăm dò mỗi 10 đến 20 giây. Hầu hết tác vụ hoàn tất trong vòng 1 đến 3 phút tùy thuộc vào model, thời lượng và kích thước.

```python theme={null}
import os
import time
import requests

TASK_ID = "<TASK_ID>"
headers = {"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}
TERMINAL = {"completed", "failed", "error"}

while True:
    response = requests.get(
        f"https://api.cometapi.com/v1/videos/{TASK_ID}",
        headers=headers,
        timeout=15,
    )
    response.raise_for_status()
    data = response.json()
    if data["status"] in TERMINAL:
        print(data.get("video_url"))
        break
    time.sleep(10)
```

## Các trường cần theo dõi

* `status` — quyết định điều kiện dừng cho vòng lặp thăm dò của bạn.
* `progress` — số nguyên từ 0 đến 100 mà bạn có thể hiển thị trong UI.
* `video_url` — URL tải xuống đã ký, có trong các phản hồi `completed`. Tải xuống Seedance sử dụng trực tiếp URL này thay vì một route `/v1/videos/{id}/content` riêng. Chữ ký có giới hạn thời gian; hãy tải xuống hoặc lưu trữ lại tệp trước khi chữ ký hết hạn.
* `completed_at` — dấu thời gian Unix tùy chọn do nền tảng trả về. Không dùng trường này để dừng thăm dò; hãy dùng `status` thay thế.
* `model` — phản hồi lại model id Seedance đã được dùng khi tác vụ được tạo.

## Các lỗi thường gặp

* HTTP `400` với `message: "task_not_exist"` nghĩa là `id` không tồn tại. Hãy xác nhận rằng bạn đã lấy `id` từ một phản hồi POST `/v1/videos` thành công và đang dùng nguyên văn giá trị đó.
* HTTP `401` nghĩa là bearer token bị thiếu hoặc không hợp lệ. Kiểm tra rằng header yêu cầu là `Authorization: Bearer $COMETAPI_KEY`.


## OpenAPI

````yaml api/openapi/video/seedance/get-seedance-query.openapi.json GET /v1/videos/{id}
openapi: 3.1.0
info:
  title: Seedance Video Task Retrieval API
  version: 1.0.0
  description: >-
    Poll a Seedance video task by id. The same endpoint serves Seedance 1.0 Pro,
    1.5 Pro, and 2.0 tasks. It returns the current status, progress, and a
    signed video_url once the task reaches completed.
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /v1/videos/{id}:
    get:
      summary: Retrieve a Seedance video task
      description: >-
        Read the latest state of a video task that was created through POST
        /v1/videos. Works for every Seedance model family. Poll every 10 to 20
        seconds until status reaches a terminal value (`completed`, `failed`, or
        `error`). `video_url` is returned on `completed` responses.
      operationId: seedance_retrieve_video
      parameters:
        - name: id
          in: path
          required: true
          description: Task id returned by POST /v1/videos.
          schema:
            type: string
          example: task_abc123
      responses:
        '200':
          description: Current Seedance video task state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoTask'
              examples:
                in_progress:
                  summary: Task still running
                  value:
                    id: task_abc123
                    object: video
                    model: doubao-seedance-2-0
                    status: in_progress
                    progress: 30
                    created_at: 1777385418
                    completed_at: 1777385485
                completed:
                  summary: Task finished successfully
                  value:
                    id: task_abc123
                    object: video
                    model: doubao-seedance-2-0
                    status: completed
                    progress: 100
                    created_at: 1777385418
                    completed_at: 1777385526
                    video_url: https://example.com/seedance-output.mp4
                failed:
                  summary: Task ended with an error
                  value:
                    id: task_abc123
                    object: video
                    model: doubao-seedance-2-0
                    status: failed
                    progress: 0
                    created_at: 1777385418
                    completed_at: 1777385526
        '400':
          description: The id does not match any task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                task_not_exist:
                  summary: Unknown task id
                  value:
                    code: null
                    message: task_not_exist
        '401':
          description: The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Bearer token rejected
                  value:
                    error:
                      code: ''
                      message: invalid token
                      type: comet_api_error
      x-codeSamples:
        - lang: Shell
          label: Retrieve task status
          source: |
            curl https://api.cometapi.com/v1/videos/<TASK_ID> \
              -H "Authorization: Bearer $COMETAPI_KEY"
        - lang: Python
          label: Retrieve task status
          source: |
            import os
            import time
            import requests

            TASK_ID = "<TASK_ID>"
            headers = {"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}
            TERMINAL = {"completed", "failed", "error"}

            while True:
                response = requests.get(
                    f"https://api.cometapi.com/v1/videos/{TASK_ID}",
                    headers=headers,
                    timeout=15,
                )
                response.raise_for_status()
                data = response.json()
                print(data["status"], data.get("progress"))
                if data["status"] in TERMINAL:
                    print(data.get("video_url"))
                    break
                time.sleep(10)
        - lang: JavaScript
          label: Retrieve task status
          source: |
            const TASK_ID = "<TASK_ID>";
            const terminal = new Set(["completed", "failed", "error"]);

            while (true) {
              const response = await fetch(
                `https://api.cometapi.com/v1/videos/${TASK_ID}`,
                { headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` } },
              );
              const data = await response.json();
              console.log(data.status, data.progress);
              if (terminal.has(data.status)) {
                console.log(data.video_url);
                break;
              }
              await new Promise((resolve) => setTimeout(resolve, 10_000));
            }
components:
  schemas:
    VideoTask:
      type: object
      required:
        - id
        - object
        - model
        - status
        - progress
        - created_at
      properties:
        id:
          type: string
          description: Task id.
        object:
          type: string
          description: Object type, always `video`.
        model:
          type: string
          description: Model id that generated the task.
        status:
          type: string
          enum:
            - queued
            - in_progress
            - completed
            - failed
            - error
          description: >-
            Task status. `queued` and `in_progress` are non-terminal.
            `completed`, `failed`, and `error` are terminal.
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Completion percentage.
        video_url:
          type:
            - string
            - 'null'
          description: >-
            Signed download URL for the finished video. Present on `completed`
            responses. Seedance downloads use this URL directly instead of a
            separate `/v1/videos/{id}/content` route. The signature is
            time-limited, so download or re-upload the file to your own storage
            soon after you receive it.
        created_at:
          type: integer
          description: Task creation time as a Unix timestamp in seconds.
        completed_at:
          type:
            - integer
            - 'null'
          description: >-
            Optional Unix timestamp returned by the platform. Use `status`, not
            this field, to decide when polling can stop.
      additionalProperties: true
    ErrorResponse:
      description: >-
        Error body. The endpoint returns one of two shapes depending on where
        the validation fails.
      oneOf:
        - type: object
          properties:
            code:
              type:
                - string
                - 'null'
            message:
              type: string
          required:
            - message
          additionalProperties: true
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type:
                    - string
                    - 'null'
                message:
                  type: string
                type:
                  type: string
              required:
                - message
                - type
              additionalProperties: true
          required:
            - error
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````