Cola de generación — Clipia Docs

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

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.

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.

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.

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

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.

Identificadores de solicitud

Un request_id suele ser un UUID. Los trabajos creados a través del servidor 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:

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 y se muestran una sola vez. Más información en Autenticación.

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.