Renderiza un storyboard con la API de films de eroq

Un solo prompt hace un clip. Una película es una secuencia de clips que comparten un look y montan bien juntos, y el modo película del estudio la construye de forma interactiva: añades una escena, la renderizas, añades la siguiente. La API de films es lo mismo sin los clics: defines el storyboard una vez, ruedas todas las escenas con una llamada, consultas los trabajos y publicas. Si produces diez variaciones del mismo spot para diez clientes, este es el endpoint que buscabas.

Una película es una receta, nunca medios

POST /v1/films guarda un título y un objeto data, tal cual. La API no interpreta la receta hasta que la renderizas, y los renders siempre llegan a tu biblioteca de creaciones, no a la película. Dos partes:

• look: lo que comparten todas las escenas (model, aspect, filmType, era, tempo, cameraType, lens, aperture, resolution).
• scenes: un array ordenado de { prompt, shot, seconds, cast }. shot es un movimiento de cámara y cast es una lista de ids de tus personajes.

curl https://eroq.ai/v1/films \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rooftop night — cut 1",
    "data": {
      "look": {
        "model": "eroq-motion-one", "aspect": "16:9",
        "filmType": "noir", "era": "1960s", "tempo": "tense",
        "cameraType": "35mm", "lens": "anamorphic", "aperture": "f1-4"
      },
      "scenes": [
        { "prompt": "A woman in a silver dress steps out onto a rooftop bar at dusk, city lights flickering on below, slow pan following her to the railing, warm practicals against the deep blue sky, wind in her hair, expectant mood.", "shot": "slow-pan", "seconds": 5 },
        { "prompt": "Close-up of her hands on the cold railing, a glass of something amber beside them, push-in as the skyline blurs behind, neon reflections crawling across the glass, quiet and tense.", "shot": "push-in", "seconds": 5 },
        { "prompt": "Wide shot from behind as she turns toward the door, a silhouette waiting there against the bar light, crane-up revealing the whole rooftop and the city beyond, patient, ominous mood.", "shot": "crane-up", "seconds": 10 }
      ]
    }
  }'

La respuesta incluye el id de la película. Hasta 50 borradores por cuenta; GET /v1/films/{id} devuelve la receta completa, PATCH actualiza title o data y DELETE elimina el borrador y deja sus renders en la biblioteca. El modo película del estudio guarda y vuelve a abrir exactamente estos borradores, así que una receta creada por script se puede abrir en /studio/video y retocar a mano, o al revés.

Escribe los prompts de escena como les gustan a los motores: un párrafo fluido que nombre sujeto, movimiento, cámara, luz y ambiente. El look aporta el resto; no repitas «cine negro, años 60» en cada escena.

Rueda todo con una llamada

curl -X POST https://eroq.ai/v1/films/FILM_ID/render \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "store": true }'

Cada escena con prompt se convierte en un trabajo de video asíncrono (un POST /v1/videos/generations por escena, con los parámetros del look incorporados) y la llamada responde 202 con un informe por escena:

{
  "id": "FILM_ID",
  "scenes": [
    { "scene": 0, "id": "job-a…", "status": "processing" },
    { "scene": 1, "id": "job-b…", "status": "processing" },
    { "scene": 2, "id": "job-c…", "status": "processing" }
  ],
  "usage": { "credits_spent": 380, "credits_remaining": 5620 }
}

Las escenas se cobran una a una y se ponen en cola en orden, así que un saldo que se agota detiene limpiamente las escenas restantes en lugar de cobrarlas a medias. Una escena que no se puede poner en cola informa de su error en su sitio (un motor bloqueado responde plan_required, por ejemplo) mientras las demás siguen adelante. Cualquier escena cuyo render falle más tarde se reembolsa sola.

Las restricciones de plan se aplican al model del look: Motion One está disponible para todas las cuentas y es el motor sin censura; Seedance, Kling, Hailuo y Veo los moderan en origen sus proveedores y necesitan el plan que los desbloquea. Los seconds por escena también los limita el plan (10, 15, 20 o 30 s).

Consulta los trabajos

Cada escena en cola es un trabajo de video normal. Consulta GET /v1/videos/generations/{id} cada pocos segundos (es gratis) hasta que status sea succeeded o failed.

const BASE = 'https://eroq.ai/v1'
const headers = { Authorization: `Bearer ${process.env.EROQ_API_KEY}` }

async function renderFilm(filmId) {
  const report = await fetch(`${BASE}/films/${filmId}/render`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ store: true }),
  }).then(r => r.json())

  const segments = []
  for (const scene of report.scenes.filter(s => s.status === 'processing')) {
    let job
    do {
      await new Promise(r => setTimeout(r, 4000))
      job = await fetch(`${BASE}/videos/generations/${scene.id}`, { headers }).then(r => r.json())
    } while (job.status === 'processing')
    if (job.status === 'succeeded') segments[scene.scene] = job.data[0].url
  }
  return segments.filter(Boolean)
}

Consultar en secuencia va bien con tres escenas; con treinta, consulta en paralelo o suscríbete al webhook video.generation.succeeded y recoge las URL a medida que llegan. En cualquier caso, terminas con las URL de los clips en orden, que es exactamente lo que pide la publicación.

Publica con portada

Dos llamadas. Primero la portada: multipart, una imagen de hasta 5 MB, gratis:

curl -X POST https://eroq.ai/v1/films/FILM_ID/cover \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -F "[email protected]"

Luego, la película en sí:

curl -X POST https://eroq.ai/v1/films/FILM_ID/publish \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rooftop night",
    "segments": ["https://…/scene-1.mp4", "https://…/scene-2.mp4", "https://…/scene-3.mp4"],
    "durationSeconds": 20
  }'

segments son de 1 a 24 URL ordenadas, y cada una debe ser un render alojado de tu propia biblioteca: los medios ajenos se rechazan. La película aparece en la vitrina de la Comunidad como una sola entrada que reproduce los segmentos uno tras otro, con la portada en la tarjeta y en el reproductor. Los espectadores ven el título, la portada, los clips y los contadores; los prompts, el look y el reparto siguen siendo privados. DELETE /v1/films/{id}/publish la retira y conserva los me gusta y los comentarios para una nueva publicación. Eliminar el borrador elimina también la entrada de la comunidad; los renders de las escenas se quedan en la biblioteca.

Lotes, para agencias

El patrón que escala: una receta por cliente como plantilla, un bucle que cambia las variables y un espacio de trabajo para que todo el equipo tire de un mismo saldo.

• Las variantes son recetas. Las mismas tres escenas en 16:9 para YouTube y en 9:16 para Reels son dos películas con dos looks. Crear, renderizar, consultar, entregar: ninguna persona en el circuito hasta la revisión.
• El costo es aritmética. Una película de tres escenas con Motion One, de 5, 5 y 10 segundos, cuesta 180 créditos, unos $1.80 a la tarifa del paquete de entrada; los 20,000 créditos mensuales del plan Studio cubren unas cincuenta, con límites de solicitudes 4×. Las tomas multiplican la cifra, así que decide cuántas alternativas necesita de verdad la revisión.
• El rendimiento es por clave. Las solicitudes de video tienen un límite por clave (6 por minuto en el nivel base, multiplicado según el plan). Dale a cada pipeline su propia clave para que el lote de un cliente nunca frene el de otro.
• Los personajes viajan. Pon al presentador habitual de un cliente en cast y la misma cara se mantiene en todas las escenas gracias a imagen a video; mira agencias para ver el flujo de trabajo completo.

Preguntas frecuentes

¿Qué pasa cuando falla una escena?

A las demás, nada. La escena fallida se reembolsa sola; vuelve a renderizarla por separado con POST /v1/videos/generations y los mismos parámetros del look, y luego mete su URL en segments. Volver a llamar a render sobre la película volvería a rodar y a cobrar todas las escenas.

¿Puedo renderizar una película que alguien creó en el estudio?

Sí. GET /v1/films lista los borradores que guardó el modo película del estudio; renderiza cualquiera de ellos por su id.

¿Publicar cuesta créditos?

No. La subida de la portada y la llamada de publicación son gratis; pagaste los renders de las escenas y nada más.

Empieza con una receta de tres escenas con los créditos gratuitos: consigue una clave de API y ruédala.