---
title: Cola de generación
description: Cómo funciona la cola asíncrona de la API REST de Clipia — envío de un trabajo, consulta del estado, obtención de resultados y webhooks para la generación de imágenes, vídeo y audio.
icon: ListOrdered
---

La API REST de Clipia genera imágenes, vídeo y audio mediante una cola asíncrona. Usted pone un trabajo en cola con `POST /v1/models/:model`, recibe un `request_id` y después recoge el resultado consultando su estado o mediante un webhook. La URL base es `https://api.clipia.ai/v1`.

No hay modo síncrono: una solicitud de generación no mantiene la conexión abierta hasta que el resultado está listo; devuelve de inmediato un identificador que le sirve para seguir el progreso.

## Ciclo de vida de una solicitud

<Steps>
<Step>
### Envío

`POST /v1/models/:model` pone la generación en cola y devuelve de inmediato un `request_id`, los enlaces `status_url` y `response_url` y el coste reservado en créditos. Consulte [Enviar una generación](/es/docs/api-reference/submit).
</Step>

<Step>
### Espera

Hay dos maneras de saber cuándo ha terminado un trabajo:

- **polling**: llame a `GET /v1/requests/:id/status` para obtener el estado, la posición en la cola y el progreso de 0 a 100;
- **webhook**: pase un `webhook_url` al enviar y Clipia enviará un `POST` firmado cuando termine el trabajo, de modo que no hace falta hacer polling. Consulte [Webhooks](/es/docs/api-reference/webhooks).
</Step>

<Step>
### Resultado

`GET /v1/requests/:id` devuelve el resultado con un campo `output` (enlaces en `media.clipia.ai`) cuando el estado es terminal, o `202` mientras la generación sigue en curso. Consulte [Resultado](/es/docs/api-reference/result).
</Step>
</Steps>

## Estados de la generación

| Estado | Descripción |
|--------|-------------|
| `IN_QUEUE` | en cola; `queue_position` es un número a partir de 0 |
| `IN_PROGRESS` | en ejecución; `progress` de 0 a 100 |
| `COMPLETED` | terminada; el resultado está disponible en `response_url` |
| `FAILED` | fallida; los créditos se reembolsan íntegramente |
| `CANCELED` | cancelada fuera de la API, por ejemplo por el equipo de soporte; estado terminal |

<Callout type="warn" title="Sin cancelación mediante la API">
La API pública no tiene endpoint de cancelación: los créditos se reservan al inicio y la mayoría de los modelos no pueden detener una generación una vez empezada. Aun así, puede aparecer un estado `CANCELED` en `status` o `result` si el trabajo se canceló fuera de la API: trátelo como definitivo.
</Callout>

## Identificadores de solicitud

Un `request_id` suele ser un UUID. Los trabajos creados a través del [servidor MCP](/es/docs/mcp) pueden llevar un prefijo: `cmp_…` para las composiciones de vídeo y `prs_…` para las presentaciones. Los endpoints de estado y de resultado aceptan las tres formas, así que no necesita tratarlas por separado. Un identificador mal formado devuelve `400`; uno desconocido, o que pertenece a otra cuenta, devuelve `404`.

## Autenticación

Cada solicitud a `/v1/*` necesita una clave de API. La cabecera recomendada:

```http
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

También se aceptan `Authorization: Key <key>` y `X-Api-Key: <key>`. Las claves se crean en la [Developer Console](/es/developer) y se muestran una sola vez. Más información en [Autenticación](/es/docs/getting-started/authentication).

<Callout type="info" title="Entorno de pruebas">
Una clave con el prefijo `clipia_test_` funciona en el entorno de pruebas: un envío no cobra créditos ni lanza ninguna generación real; devuelve `status: COMPLETED` de inmediato con un recurso de ejemplo fijo. Consulte [Entorno de pruebas](/es/docs/getting-started/sandbox).
</Callout>