Realización de vídeos

Cada vídeo comienza con una llamada: POST /v1/render. Esta página explica las decisiones que haces en esa llamada. Para cada campo y sus límites, consulta la referencia Create render.

Resumen o plan de escena

Manda uno de estos.

Un resumen

Un brief es una descripción en lenguaje sencillo del vídeo, de hasta 4.000 caracteres. Reigniter planifica las escenas, escribe la narración y comienza el renderizado.

{
  "brief": "A 30 second advert for Northwind Coffee's weekly subscription. Show the beans, the roasting, and a happy customer opening the box.",
  "kind": "ad",
  "duration_sec": 30,
  "brand_name": "Northwind Coffee",
  "category": "coffee"
}

Campos que conforman el plan:

Campo	Default	Qué hace
kind	ad	ad para un anuncio, training para un vídeo de formación.
duration_sec	20 por ad, 60 por training	Longitud total del objetivo, de 5 a 120 segundos.
narrator	true	false hace un vídeo sin voz en off.
brand_name	ninguno	La marca que debería usar el planificador.
category	ninguno	La categoría de producto, por ejemplo coffee o saas.
title	escrito para ti	Un título para el vídeo.

La planificación gasta créditos. Si la planificación falla, te 502 PLAN_FAILED y los créditos de planificación se devuelven. Si envías plan_notes de vuelta a una persona, te explican todo lo que el planificador ha marcado en su propio plan.

Un plan de escena

Un scene_plan es tu propia lista de 1 a 12 escenas, renderizadas en orden, según se indica. Úsala cuando ya sepas qué debe mostrar y decir cada escena.

{
  "title": "Northwind launch",
  "scene_plan": [
    {
      "type": "motion",
      "role": "hook",
      "prompt": "Fresh coffee, delivered weekly",
      "script": "Fresh coffee, delivered every week.",
      "motion": { "beat": "hook" }
    },
    {
      "type": "t2v_fast",
      "role": "body",
      "prompt": "Slow close-up of coffee beans tumbling out of a kraft paper bag onto a wooden table, soft morning light",
      "script": "Roasted in small batches, a few days before it reaches you."
    },
    {
      "type": "motion",
      "role": "cta",
      "prompt": "Order at northwind.example",
      "script": "Order today.",
      "motion": { "beat": "cta" }
    }
  ]
}

Tipos de escenas:

type	Qué renderiza
motion	Texto animado nítido, números, pasos o un logotipo. Úsalo para cualquier cosa que deba ser legible.
t2v_fast	Generó imágenes de personas, lugares u objetos, de prompt.
i2v_fast	Metraje generado que comienza a partir de una imagen: la escena ref_image_urlo la foto de tu producto.
s2v	Un presentador hablando a la cámara. Necesita una cara.
walk_talk	Un presentador caminando y hablando. Necesita una cara.
footage	Tu propio clip de video_url, reproducido tal cual.

Cada escena toma un prompt (lo que ve la cámara, o la copia en pantalla para motion) y un script opcional (la frase del narrador). La lista completa de campos de escena está en la referencia.

Consejo

El metraje generado es pobre para leer el texto. Pon pantallas, precios, pasos y eslóganes en motion escenas, y mantén t2v_fast para el mundo real.

Marca

Un render API nunca detecta una marca por sí solo, aunque tu cuenta tenga kits de marca. Eliges la marca en cada solicitud:

• brand_logo_url: tu logo, como URL https pública o URI de datos.
• brand_colors: opcional, hasta 12 colores hexadecimales, como ["#3B2416", "#F4E9DC"].

{
  "brief": "A 20 second advert for Northwind Coffee.",
  "brand_logo_url": "https://example.com/northwind-logo.png",
  "brand_colors": ["#3B2416", "#F4E9DC"]
}

Sin logo, el vídeo se renderiza sin logo ni tarjeta final. Para decirlo explícitamente, envía brand_enabled: false.

Kits de marca

brand_kit_id nombra uno de tus kits de marca guardados. Por ahora, envíalo junto con brand_logo_url. Un brand_kit_id solo se rechaza con 422 BRAND_REQUIRED. Un kit que pertenece a otra cuenta nunca se usa.

Foto del producto

product_image_url es una foto de tu producto (una URL https pública o un URI de datos). Mantiene el producto igual en cada escena, en lugar de dejar que el modelo invente uno.

Algunos formatos venden un producto y necesitan una foto. Si configuras un route así (por ejemplo, product-ad, unboxing, ugc-ad o app-demo) y el plano muestra el producto, un render sin foto se rechaza con 400 PRODUCT_IMAGE_REQUIRED. Para renderizar sin una a propósito, envía product_enabled: false.

Presentador

s2v y walk_talk escenas muestran a una persona hablando. Necesitan una cara: avatar_preset_id para todo el vídeo, o ref_image_url en la escena. Un plan con una escena de diálogo y sin cara se rechaza con 400 PRESENTER_REQUIRED. Para que Reigniter puedas usar un presentador de archivo, envía presenter_enabled: false.

Nada que ancle el vídeo

Cuando configuras un route y no envías ni marca, ni foto de producto ni presentador, y el plan generaría todas sus imágenes, el render se rechaza con 422 NO_ANCHOR. Sin un ancla, el modelo inventa el producto y a las personas, y no coincidirán con tu marca.

Añade uno de los tres, o envía product_enabled: false o presenter_enabled: false para renderizar de todas formas.

Se planifican informes antes de estas comprobaciones

Con un brief, la planificación ocurre primero y se cobra. Si la presentación planificada es rechazada por uno de los cheques anteriores, los créditos de planificación no se devuelven. Envía la marca, la foto del producto o el presentador con el brief, para que el cheque pase a la primera.

Aspecto y sonido

Campo	Valores	Default
aspect	9:16, 16:9, 1:1, 4:5, 4:3, 3:4	9:16
quality	draft, standard, premium	draft
language	un código de lenguaje, como en, fr, de	en
art_style	cinematic, stop_motion, mascot, watercolour, whimsy_3d	cinematic
music_style	upbeat-tech, cinematic-epic, lo-fi-chill, corporate-pop	establecido por el formato
voice_preset_id	una identificación de voz de narrador	una voz por defecto
upscale	true o false	establecida por el formato y la calidad

Más quality y upscale cuestan más créditos y tardan más.

Vídeos de formación

Configura kind: "training" con un brief para planificar un vídeo de formación en lugar de un anuncio. El planificador escribe los pasos y un resumen, y utiliza escenas motion para instrucciones en pantalla.

{
  "brief": "How to reset a password in the Acme admin panel. Three steps, then a recap.",
  "kind": "training",
  "duration_sec": 60,
  "aspect": "16:9",
  "brand_logo_url": "https://example.com/acme-logo.png"
}

Reintentos e idempotencia

Envía una cabecera Idempotency-Key con un valor único, como un UUID, en cada renderizado. Si tu petición expira y lo intentas de nuevo con la misma clave, Reigniter rechaza la repetición y no renderiza ni cobra una segunda vez.

• La repetición se rechaza, por lo que no devuelve el job_id original. Guarda el job_id de la primera respuesta cuando recibas una.
• Con un scene_plan, la repetición devuelve 409 DUPLICATE_REQUEST.
• Con un brief, la repetición puede devolver 402 con el mensaje This request was already submitted. Trátalo igual que un 409.
• Usa una nueva clave para cada vídeo nuevo. Reutilizar una clave para otro vídeo diferente rechaza ese vídeo.

Sin el encabezado, cada llamada es un nuevo renderizado y un nuevo cargo.

Marcas de agua

La respuesta de renderizado tiene un campo watermarked. Los vídeos hechos con el plano Agency no tienen marca de agua.

Producción

Cuando el trabajo tiene éxito, video_url en GET /v1/job/{id} hay un enlace directo al MP4. Descárgalo y guarda tu propia copia.