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

# Seedance 비디오 조회

> CometAPI에서 GET /v1/videos/{id}로 id를 기준으로 Seedance 비디오 작업을 폴링합니다. Seedance 1.0 Pro, 1.5 Pro, 2.0 작업에서 동작합니다. 작업이 completed에 도달하면 현재 status, progress, 그리고 서명된 video_url을 반환합니다.

이 엔드포인트를 사용하면 [Seedance 비디오 생성](./create)을 통해 생성된 작업의 상태를 읽을 수 있습니다. 경로의 `id`는 어떤 Seedance 모델이 작업을 생성했는지와 관계없이 create 호출이 반환한 값입니다.

응답 본문은 비디오 작업 객체 자체입니다. 최상위 수준에서 `status`, `progress`, `video_url`를 확인하세요.

## 상태 머신

API는 소문자 상태 문자열을 반환합니다. `queued`와 `in_progress`는 비종료 상태이며, `completed`, `failed`, `error`는 종료 상태이므로 작업 상태가 더 이상 변경되지 않습니다.

| Status        | 의미                               | 종료 여부 |
| ------------- | -------------------------------- | ----- |
| `queued`      | 수락되어 렌더링 대기열에 들어간 상태입니다.         | 아니요   |
| `in_progress` | 렌더링이 진행 중입니다.                    | 아니요   |
| `completed`   | 완료되었습니다. 응답에 `video_url`가 포함됩니다. | 예     |
| `failed`      | 제공자가 작업을 거부했습니다.                 | 예     |
| `error`       | 내부 오류로 인해 완료되지 못했습니다.            | 예     |

## 폴링 주기

10초에서 20초마다 폴링하세요. 대부분의 작업은 모델, 길이, 크기에 따라 1\~3분 내에 완료됩니다.

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

## 확인할 필드

* `status` — 폴링 루프의 중단 조건을 결정합니다.
* `progress` — UI에 표시할 수 있는 0\~100의 정수입니다.
* `video_url` — 서명된 다운로드 URL이며, `completed` 응답에 포함됩니다. Seedance 다운로드는 별도의 `/v1/videos/{id}/content` 경로 대신 이 URL을 직접 사용합니다. 서명에는 시간 제한이 있으므로 만료되기 전에 파일을 다운로드하거나 다시 호스팅하세요.
* `completed_at` — 플랫폼이 반환하는 선택적 Unix 타임스탬프입니다. 폴링 중단 조건으로 사용하지 말고 대신 `status`를 사용하세요.
* `model` — 작업 생성 시 사용된 Seedance model id를 그대로 반환합니다.

## 일반적인 오류

* HTTP `400`에서 `message: "task_not_exist"`가 반환되면 `id`를 알 수 없다는 뜻입니다. POST `/v1/videos`의 성공 응답에서 `id`를 가져왔는지, 그리고 그것을 그대로 사용하고 있는지 확인하세요.
* HTTP `401`은 bearer token이 없거나 유효하지 않음을 의미합니다. 요청 헤더가 `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.

````