Fazendo vídeos

Todo vídeo começa com uma chamada: POST /v1/render. Esta página explica as escolhas que você faz nessa chamada. Para cada campo e seus limites, veja a referência Create render.

Resumo ou plano de cena

Mande um desses.

Um resumo

Um brief é uma descrição em linguagem simples do vídeo, com até 4.000 caracteres. Reigniter planeja as cenas, escreve a narração e inicia a renderização.

{
  "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 moldam o plano:

Campo	Padrão	O que ele faz
kind	ad	ad para um anúncio, training para um vídeo de treinamento.
duration_sec	20 por ad, 60 por training	Comprimento total do alvo, de 5 a 120 segundos.
narrator	true	false faz um vídeo sem narração.
brand_name	nenhum	O nome da marca que o planejador deve usar.
category	nenhum	A categoria de produto, por exemplo, coffee ou saas.
title	escrito para você	Um título para o vídeo.

Planejamento gasta créditos. Se o planejamento falhar, você recebe 502 PLAN_FAILED e os créditos de planejamento são reembolsados. Se você enviar plan_notes de volta para uma pessoa, ela explica tudo o que o planejador sinalizou em seu próprio plano.

Um plano de cena

Um scene_plan é sua própria lista de 1 a 12 cenas, renderizadas em ordem, conforme dado. Use-a quando você já souber o que cada cena deve mostrar e dizer.

{
  "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 cena:

type	O que ele renderiza
motion	Texto animado nítido, números, passos ou um logo. Use para qualquer coisa que precise ser legível.
t2v_fast	Gerou imagens de pessoas, lugares ou objetos, de prompt.
i2v_fast	Imagens geradas que começam a partir de uma imagem: a ref_image_url da cena ou a foto do seu produto.
s2v	Um apresentador falando para a câmera. Precisa de um rosto.
walk_talk	Um apresentador andando e falando. Precisa de um rosto.
footage	Seu próprio clipe de video_url, tocado como está.

Cada cena leva um prompt (o que a câmera vê, ou a cópia na tela para motion) e um script opcional (a fala do narrador). A lista completa de campos de cena está na referência.

Dica

As imagens geradas são ruins para ler texto. Coloque telas, preços, passos e slogans em motion cenas e mantenha t2v_fast para o mundo real.

Marca

Um render API nunca capta uma marca sozinho, mesmo que sua conta tenha kits de marca. Você escolhe a marca em cada pedido:

• brand_logo_url: seu logo, como uma URL https pública ou um URI de dados.
• brand_colors: opcional, até 12 cores hexagonais, como ["#3B2416", "#F4E9DC"].

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

Sem logo, o vídeo é renderizado sem logo e sem cartão final. Para dizer isso explicitamente, envie brand_enabled: false.

Kits de marca

brand_kit_id nomeia um dos seus kits de marca salva. Por enquanto, envie junto com brand_logo_url. Um brand_kit_id sozinho é recusado com 422 BRAND_REQUIRED. Um kit que pertence a outra conta nunca é usado.

Foto do produto

product_image_url é uma foto do seu produto (uma URL https pública ou um URI de dados). Ela mantém o produto igual em todas as cenas, em vez de deixar o modelo inventar um.

Alguns formatos vendem um produto e precisam de uma foto. Se você definir um route (por exemplo, product-ad, unboxing, ugc-ad ou app-demo) e o plano mostrar o produto, uma renderização sem foto é recusada com 400 PRODUCT_IMAGE_REQUIRED. Para renderizar sem uma de propósito, envie product_enabled: false.

Apresentador

s2v e walk_talk cenas mostram uma pessoa falando. Eles precisam de um rosto: avatar_preset_id para o vídeo inteiro, ou ref_image_url na cena. Um plano com uma cena de conversa e sem rosto é recusado com 400 PRESENTER_REQUIRED. Para permitir que Reigniter use um apresentador de repertório, envie presenter_enabled: false.

Nada que ancorasse o vídeo

Quando você define um route e não envia marca, nem foto do produto, nem apresentador, e o plano geraria todas as fotos, o render é recusado com 422 NO_ANCHOR. Sem um anchor, o modelo inventa o produto e as pessoas, e elas não combinam com sua marca.

Adicione um dos três, ou envie product_enabled: false ou presenter_enabled: false para renderizar mesmo assim.

Os briefings são planejados antes dessas verificações

Com um brief, o planejamento acontece primeiro e é cobrado. Se a renderização planejada for recusada por um dos cheques acima, os créditos de planejamento não são reembolsados. Envie a marca, foto do produto ou apresentador com o briefing, para que o cheque passe na primeira vez.

Aparência e som

Campo	Valores	Padrão
aspect	9:16, 16:9, 1:1, 4:5, 4:3, 3:4	9:16
quality	draft, standard, premium	draft
language	um código de linguagem, 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	definido pelo formato
voice_preset_id	um narrador por voz	uma voz padrão
upscale	true ou false	definido pelo formato e qualidade

Níveis mais altos quality e upscale custam mais créditos e levam mais tempo.

Vídeos de treinamento

Defina kind: "training" com um brief para planejar um vídeo de treinamento em vez de um anúncio. O planejador escreve passos e um resumo, e usa motion cenas para instruções na tela.

{
  "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"
}

Retentativas e idempotência

Envie um cabeçalho Idempotency-Key com um valor único, como um UUID, em cada render. Se sua solicitação expirar e você tentar novamente com a mesma chave, Reigniter recusa a repetição e não renderiza nem cobra uma segunda vez.

• A repetição é recusada, então não retorna a job_id original. Salve o job_id da primeira resposta sempre que receber uma.
• Com scene_plan, a repetição retorna 409 DUPLICATE_REQUEST.
• Com um brief, a repetição pode retornar 402 com a mensagem This request was already submitted. Trate isso da mesma forma que um 409.
• Use uma nova chave para cada novo vídeo. Reutilizar uma chave para um vídeo diferente faz com que esse vídeo seja recusado.

Sem o cabeçalho, cada chamada é uma nova renderização e uma nova carga.

Marcas d’água

A resposta de renderização tem um campo watermarked. Vídeos feitos no plano Agency não são marcados por marca d’água.

Produção

Quando o trabalho der certo, video_url em GET /v1/job/{id} é um link direto para o MP4. Baixe e guarde sua própria cópia.