Solución de API de vídeo
El vídeo es lo más caro que genera la mayoría de los productos y lo que más tarda en volver. Tres campos del cuerpo deciden ambas cosas, y la tarea sigue viva mucho después de que desaparezca la petición que la lanzó.
El reto
Una petición de vídeo no es una petición de imagen más lenta. La duración, la resolución y el interruptor de audio fijan lo que pagas y lo que esperas, y lo hacen antes de que exista un solo fotograma.
01
La mayoría de endpoints de vídeo cobran por segundo producido en la resolución elegida. Pasar duration_seconds de 5 a 10 duplica aproximadamente el cargo; subir un escalón de resolución lo vuelve a hacer. Ambos están marcados como relevantes para el precio en el esquema, así que la estimación va junto al control, no en la factura.
02
Donde existe generate_audio, ese booleano mueve la petición a otra tarifa. Un formulario que lo oculta enviará en silencio la versión más cara cada vez.
03
createTask responde 202 Accepted con un taskId en estado queued. La generación continúa en el servidor durante minutos. Cualquier código que espere en el socket original agotará el tiempo mientras la tarea, y el cargo, siguen adelante.
El enfoque
Pide una estimación del cuerpo exacto con POST /api/v1/jobs/quote, muestra el importe y envía ese mismo cuerpo a createTask con quoteId, expectedCost y una Idempotency-Key guardada. Un precio que cambió entre ambas llamadas falla con el código de negocio 40901 en lugar de aparecer más tarde en la factura.
Una llamada de creación lleva el modelo, la entrada validada y una devolución opcional. HTTP 202 significa aceptado, no terminado.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p",
"generate_audio": true
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}Contrato
| Campo o cabecera | Valor o límite |
|---|---|
| POST /api/v1/jobs/createTask | 202 Accepted · state queued |
| duration_seconds · resolution · generate_audio | price-affecting fields |
| Idempotency-Key | 24 h · scoped to one API key |
| output.assets[].expiresAt | signed URL · results kept 14 days |
Desliza horizontalmente para ver todas las columnas.
Integración
Encaje
Comprobaciones
El formulario de cada página de modelo se genera desde el input_schema de ese endpoint, y el servidor valida contra el mismo documento. Un campo no declarado devuelve 400 en vez de descartarse en silencio.
createTask reserva el importe estimado y lo devuelve en cost con settled: false. El cargo final nunca supera la reserva, y un fallo o caducidad la libera por completo.
Limita una clave por día, por mes y durante toda su vida, restríngela a modelos concretos y a IP de origen, y envía cada escritura con la misma clave de idempotencia.
Antes del lanzamiento
Preguntas frecuentes
Modelos
Cada enlace abre la página de esa familia de modelos: entradas, límites, política de contenido y el precio actual por unidad.
Siguiente paso
Compara endpoints de vídeo por duración, resolución, audio y precio, y envía después la misma petición desde tu servidor.
