Cómo elegir una API de video con IA: jobs, webhooks y reembolsos

Elegir una API de video con IA no es como elegir una API de imágenes. Un render de video tarda minutos, no segundos, y eso significa que la forma de la integración (no la calidad de los fotogramas) determina cuánto de tu semana te va a costar. Si eliges mal el modelo de jobs, más adelante estarás reescribiendo tu cola, tus reintentos y tu conciliación de facturación. Estas son las siete cosas que conviene comprobar antes de escribir la primera solicitud, con las formas de eroq como ejemplo práctico.

1. Jobs asíncronos, no una llamada bloqueante

Una solicitud HTTP bloqueante que espera a que termine un video es una trampa disfrazada de comodidad. Los balanceadores de carga, las plataformas serverless y las CDN tienen límites de duración por solicitud muy por debajo de un render largo, así que una API bloqueante funciona en las pruebas y muere en producción justo en el momento en que un render tarda más de lo habitual.

La forma correcta es un job. En eroq, POST /v1/videos/generations devuelve un id de job de inmediato; después consultas GET /v1/videos/generations/{id} o esperas un webhook. Referencia completa en /docs/video.

# 1. submit
curl -X POST https://eroq.ai/v1/videos/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-lite",
    "prompt": "A courier weaves a bicycle between stopped cars on a wet avenue at dusk, headlights smearing across the frame. Tracking shot, 35mm film, anamorphic lens, neon noir palette, dynamic tempo.",
    "seconds": 5,
    "aspect": "9:16"
  }'

# 2. poll (or skip this and use a webhook)
curl https://eroq.ai/v1/videos/generations/JOB_ID \
  -H "Authorization: Bearer $EROQ_API_KEY"

Qué comprobar en otros proveedores: si el endpoint de video es realmente asíncrono y si existe un endpoint de listado para recuperar jobs después de reiniciar un proceso. Si el único registro de un render es la respuesta que perdiste, vas a perder renders.

2. Webhooks que de verdad puedas verificar

El polling sirve para empezar y es un desperdicio a gran volumen. Un webhook debería llegar firmado, y el esquema de firma debería ser uno que ya hayas implementado antes.

eroq emite video.generation.succeeded y video.generation.failed con una cabecera de firma al estilo de Stripe, y el payload lleva una URL de CDN en lugar de base64 incrustado. Eso importa, porque un cuerpo JSON de varios megabytes acabará rompiendo algo en tu stack.

Tres preguntas para cualquier proveedor: ¿el payload va firmado?, ¿hay una ventana contra repeticiones (replay) dentro del material firmado? y ¿el cuerpo lleva una URL o los bytes? Verifica sus respuestas en su documentación, a fecha de septiembre de 2026.

3. Qué pasa cuando un render falla

Este es el criterio que separa una plataforma de verdad de un simple wrapper, y casi nunca aparece en la página de precios. Pregunta tres cosas:

¿Se reembolsan los fallos? En eroq, las generaciones fallidas se reembolsan automáticamente. Concilias éxitos, no intentos.

¿Se cobran los rechazos por política? Una solicitud bloqueada devuelve content_blocked y nunca se cobra. A escala, una plataforma que cobra los rechazos te está cobrando por su propio filtro.

¿La comprobación ocurre antes o después del cargo? Un modelo que tu plan no incluye devuelve 403 plan_required antes de que se mueva ningún crédito; un motor sin capacidad aprovisionada devuelve 503 model_unavailable, también antes del cargo. Tampoco hay sustitución silenciosa por otro motor: si pediste un modelo concreto y no está disponible, recibes un error, no un renderizador sorpresa. La sustitución silenciosa es el peor modo de fallo de esta categoría, porque tu resultado cambia y tus logs no.

4. La unidad de facturación

Dominan dos modelos: la medición por segundo y los créditos fijos por clip en duraciones de referencia. Las tarifas fijas son más fáciles de presupuestar y de explicar a un equipo de finanzas; el cobro por segundo es más justo con duraciones irregulares. Ninguno está mal, pero necesitas saber en cuál estás antes de prometerle un precio a un cliente.

eroq cobra créditos con tarifas fijas por motor: 120 créditos por 5 segundos con Seedance 1.0 Lite, 60 con Motion One, 170 con Kling 2.5 Turbo, 216 por los 8 segundos fijos de Veo 3 Fast, y así con todo el catálogo en /models. Un crédito equivale más o menos a un centavo con el paquete de entrada. Los créditos nunca caducan, y un espacio de trabajo tiene un único saldo compartido entre sus puestos y sus claves, lo que convierte la contabilidad por cliente en tarea tuya en lugar de un montón de relaciones de facturación separadas. Si revendes generación, la mecánica para trasladar los costos medidos está en precios por créditos para APIs de IA.

5. Límites de solicitudes que escalan con el plan

Los límites por clave en eroq empiezan en 60 solicitudes por minuto para chat, 20 para imágenes y 6 para video y voz, multiplicados según el plan: ×2 en Creator, ×4 en Studio, ×6 en Team, ×8 en Agency. El número de claves también sube con el plan: 10 claves en Hobby, 20 en Creator, 50 en Studio, 100 en Team, 200 en Agency. Los puestos son la excepción: todos los planes individuales se quedan en 2, y un equipo de verdad pasa a Team (25 puestos) o a Agency (50).

El consejo práctico es emitir una clave por entorno y otra por cada superficie de cara al cliente, para que un bucle descontrolado en staging solo frene staging. Comprueba si los límites de cualquier proveedor son por clave o por cuenta, porque cada opción produce un radio de impacto muy distinto.

6. Descubrimiento, para no fijar el catálogo en el código

Los catálogos cambian. Si escribes a fuego en tu app los ids de los motores y los precios, acabarás publicando un menú desactualizado.

GET /v1/engines devuelve cada motor con su restricción de plan, su disponibilidad y sus capacidades (si admite seed, fotograma final, prompt negativo, audio), y GET /v1/models devuelve la lista completa de modelos con precios. Construye tu interfaz a partir de esas dos respuestas y los motores nuevos aparecerán solos. La especificación es legible por máquina en /openapi.json, y hay un /llms.txt para agentes de programación.

7. Superficies para agentes: MCP y CLI

Cada vez más, lo que llama a tu API de video no es tu app, sino un agente. Hay dos superficies que vale la pena tener:

Un servidor MCP remoto. El de eroq está en https://eroq.ai/mcp sobre Streamable HTTP, se autentica con la misma clave Bearer y expone generate_image, generate_video, get_video_status, generate_speech, enhance_prompt, list_models, list_voices, list_characters y get_account. Se conecta a ChatGPT como conector personalizado, a Claude en la web y en escritorio, a Cursor y a Codex CLI. Para los clientes que no pueden enviar cabeceras existe la forma /mcp/<key>, en la que la URL es el secreto y debe tratarse como tal. Configuración por cliente en /docs/mcp.

claude mcp add --transport http eroq https://eroq.ai/mcp \
  --header "Authorization: Bearer $EROQ_API_KEY"

Una CLI. El paquete eroq funciona con Node 18+ sin ninguna dependencia: eroq login, eroq image "…", eroq video "…" -s 8 --aspect 9:16, eroq speech "…" -v aria. eroq mcp arranca un servidor MCP stdio local que escribe los medios en archivos, que es justo la forma que quieren los agentes de programación.

Dos cosas más, una vez superado lo básico

Estructura por lotes. Si renderizas secuencias en lugar de piezas sueltas, busca un recurso que modele la secuencia. El recurso films de eroq guarda un storyboard, y POST /v1/films/{id}/render rueda todas las escenas, cobra por escena y se detiene limpiamente cuando un saldo se queda vacío: consulta /docs/films.

Alojar el resultado. Las URL de los renders no son almacenamiento permanente. Cópialas a tu propio bucket al recibir el webhook de éxito, o usa el eroq Store en /v1/storage/objects (2 créditos por 10 MB) y quédate con un único sistema de registro.

La lista de verificación

1. Job asíncrono con un endpoint de listado para recuperar renders.
2. Webhooks firmados que llevan URL, no bytes.
3. Reembolsos automáticos en caso de fallo y ningún cobro por rechazos de política.
4. Comprobaciones de plan antes del cargo y ninguna sustitución silenciosa de motor.
5. Una unidad de facturación que puedas cotizarle a un cliente.
6. Límites de solicitudes por clave que escalan con el plan.
7. Descubrimiento en tiempo de ejecución de modelos, precios y capacidades.

Pasa esa lista por cualquier proveedor, incluido este. Todo lo anterior está documentado en /docs, con sus precios en /pricing.

Preguntas frecuentes

¿La API de video de eroq es síncrona o asíncrona?

Asíncrona. POST /v1/videos/generations devuelve un id de job, y puedes consultar el job o recibir un webhook firmado video.generation.succeeded. Un endpoint de listado devuelve los jobs recientes del espacio de trabajo, así que un reinicio nunca hace perder un render.

¿Me cobran si falla un render de video?

No. Las generaciones fallidas se reembolsan automáticamente, y las solicitudes bloqueadas por la política de contenido devuelven content_blocked sin cargo. Las restricciones de plan y los motores no disponibles se comprueban antes de que se mueva ningún crédito.

¿Puedo llamar a la API de video desde un agente en lugar de hacerlo desde código?

Sí: un servidor MCP remoto en https://eroq.ai/mcp expone herramientas de generación, estado y cuenta a ChatGPT, Claude, Cursor y Codex, y la CLI eroq incluye un servidor MCP stdio local que guarda los renders como archivos.

Consigue una clave de API y envía tu primer job: /signup.