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

# Recuperar un video de Seedance

> Consulta una tarea de video de Seedance por id en CometAPI con GET /v1/videos/{id}. Funciona para tareas de Seedance 1.0 Pro, 1.5 Pro y 2.0. Devuelve el estado actual, el progreso y el `video_url` firmado después de que la tarea alcance completed.

Usa este endpoint para leer el estado de una tarea creada mediante [Create a Seedance video](./create). El `id` en la ruta es el valor devuelto por la llamada de creación, independientemente de qué modelo de Seedance haya producido la tarea.

El cuerpo de la respuesta es el propio objeto de tarea de video. Lee `status`, `progress` y `video_url` en el nivel superior.

## Máquina de estados

La API devuelve cadenas de estado en minúsculas. `queued` e `in_progress` no son terminales; `completed`, `failed` y `error` son terminales y la tarea no volverá a cambiar.

| Status        | Significado                                            | Terminal |
| ------------- | ------------------------------------------------------ | -------- |
| `queued`      | Aceptada y en cola para renderizarse.                  | no       |
| `in_progress` | Renderizado en curso.                                  | no       |
| `completed`   | Finalizada. `video_url` está presente en la respuesta. | sí       |
| `failed`      | El proveedor rechazó la tarea.                         | sí       |
| `error`       | Un error interno impidió la finalización.              | sí       |

## Cadencia de sondeo

Haz polling cada 10 a 20 segundos. La mayoría de los trabajos terminan en 1 a 3 minutos, según el modelo, la duración y el tamaño.

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

## Campos que debes vigilar

* `status` — determina la condición de parada de tu bucle de polling.
* `progress` — entero de 0 a 100 que puedes mostrar en una UI.
* `video_url` — URL de descarga firmada, presente en respuestas `completed`. Las descargas de Seedance usan esta URL directamente en lugar de una ruta `/v1/videos/{id}/content` separada. La firma tiene tiempo limitado; descarga o vuelve a alojar el archivo antes de que la firma expire.
* `completed_at` — marca de tiempo Unix opcional devuelta por la plataforma. No la uses para detener el polling; usa `status` en su lugar.
* `model` — refleja el model ID de Seedance usado cuando se creó la tarea.

## Errores comunes

* HTTP `400` con `message: "task_not_exist"` significa que el `id` es desconocido. Confirma que capturaste el `id` de una respuesta POST `/v1/videos` correcta y que lo usas textualmente.
* HTTP `401` significa que el bearer token falta o no es válido. Comprueba que el encabezado de la solicitud sea `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.

````