Migración desde otra API de generación

Si su servicio ya utiliza otra API de generación de imágenes, vídeo o audio basada en una cola, pasar a Clipia suele consistir en cambiar la URL, la clave y la forma de algunos campos. Esta página explica cómo funciona la cola de Clipia, qué revisar en su código y en qué puede diferir Clipia de lo que usted ya conoce.

Cómo funciona la cola de Clipia

La generación en Clipia es asíncrona y consta de tres pasos:

1. POST https://api.clipia.ai/v1/models/{model}: envíe un trabajo. La respuesta incluye request_id, status_url, response_url y cost, el importe reservado en créditos.
2. GET /v1/requests/{request_id}/status: el estado, que puede ser IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED o CANCELED.
3. GET /v1/requests/{request_id}: el resultado, con enlaces a los archivos multimedia terminados.

En lugar de consultar el estado, puede indicar un webhook_url, y Clipia envía un POST cuando el trabajo termina. Consulte la descripción general de la API.

Qué cambiar en su código

curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b" \
  -d '{ "input": { "prompt": "a sunset over mountains" }, "webhook_url": "https://example.com/clipia-webhook" }'

Los nombres y los parámetros de los modelos difieren de una API a otra. Compare cada modelo con su esquema input en el catálogo: GET /v1/models/{model} devuelve el esquema completo.

Clave

Cree una clave en la consola para desarrolladores; solo se muestra una vez. Las claves con el prefijo clipia_live_ funcionan en producción, y las claves con el prefijo clipia_test_ funcionan en el entorno de pruebas, que devuelve un resultado predefinido sin cobrar créditos. Guarde la clave en la variable de entorno CLIPIA_KEY y no la envíe nunca al navegador. Consulte Autenticación.

Webhooks

El cuerpo de un webhook contiene request_id, status (OK o ERROR) y, o bien un payload con el modelo, los enlaces al resultado y el importe cobrado, o bien un error con un código y un mensaje. La firma es HMAC-SHA256 en la cabecera X-Clipia-Signature, con el formato t=<timestamp>,v1=<hex>; la hora de envío figura en X-Clipia-Timestamp. Cada clave de API tiene su propio secreto de webhook, que solo se muestra una vez.

Un controlador escrito para otro formato de firma debe reescribirse. Pruébelo con una clave clipia_test_: en el entorno de pruebas, los webhooks se firman igual que en producción. Consulte Webhooks.

En qué puede diferir Clipia

• Créditos. Los costes se expresan en créditos, no en moneda. Para conocer el precio antes de ejecutar, llame a POST /v1/models/{model}/estimate. Si una generación falla, los créditos se devuelven.
• La falta de créditos es 402. El código es insufficient_credits; si su código esperaba otro estado, actualice esa rama.
• Sin cancelación. La API pública no tiene endpoint de cancelación. Aun así, puede recibir CANCELED si un trabajo se canceló fuera de la API, por ejemplo el equipo de soporte: trátelo como estado final.
• Un único formato de error. Un objeto error con type, code y message; consulte Errores.
• Límites. 120 solicitudes por minuto por clave y 600 entre todas las claves de una cuenta, con cabeceras RateLimit-*; consulte Límites de solicitudes.

Lista de comprobación previa al lanzamiento

1. Cada modelo tiene un slug del catálogo y su esquema input está revisado.
2. La clave está en CLIPIA_KEY en el servidor, y la integración se ha probado con una clave clipia_test_.
3. Cada envío incluye su propio Idempotency-Key.
4. El controlador de webhooks verifica X-Clipia-Signature y elimina las entregas duplicadas por request_id.
5. Se gestionan los estados FAILED y CANCELED y los códigos 402 y 429.

Clientes de cola listos para usar: SDK de TypeScript y SDK de Python. Para consejos generales de fiabilidad, consulte Buenas prácticas.