Realizzazione di video

Ogni video inizia con una chiamata: POST /v1/render. Questa pagina spiega le scelte che fai in quella chiamata. Per ogni campo e i suoi limiti, vedi il riferimento Create render.

Breve o piano della scena

Manda uno di questi.

Un breve riassunto

Un brief è una descrizione in modo semplice del video, fino a 4.000 caratteri. Reigniter pianifica le scene, scrive la narrazione e inizia il rendering.

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

Campi che modellano il piano:

Campo	Predefinito	Cosa fa
kind	ad	ad per una pubblicità, training per un video di formazione.
duration_sec	20 per ad, 60 per training	Lunghezza totale del bersaglio, da 5 a 120 secondi.
narrator	true	false realizza un video senza doppiaggio.
brand_name	nessuna	Il nome del marchio che il planner dovrebbe usare.
category	nessuna	La categoria di prodotto, ad esempio coffee o saas.
title	scritto per te	Un titolo per il video.

La pianificazione spendono crediti. Se la pianificazione fallisce, ricevi 502 PLAN_FAILED e i crediti di pianificazione vengono rimborsati. Se invii plan_notes a una persona, ti spiega tutto ciò che il pianificatore ha segnalato nel suo piano.

Un piano di scena

Un scene_plan è la tua lista di 1 a 12 scene, renderizzate in ordine, come indicato. Usalo quando sai già cosa dovrebbe mostrare e dire ogni scena.

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

Tipi di scene:

type	Cosa renderizza
motion	Testo animato nitido, numeri, passi o un logo. Usalo per qualsiasi cosa debba essere leggibile.
t2v_fast	Generò filmati di persone, luoghi o oggetti, da prompt.
i2v_fast	Filmati generati che partono da un’immagine: la ref_image_url della scena o la foto del tuo prodotto.
s2v	Un presentatore che parla alla telecamera. Serve un volto.
walk_talk	Un presentatore che cammina e parla. Serve un volto.
footage	Il tuo video da video_url, riprodotto così com’è.

Ogni scena richiede un prompt (ciò che vede la telecamera, o la copia sullo schermo per motion) e un script opzionale (la battuta del narratore). L’elenco completo dei campi della scena si trova nel riferimento.

Consiglio

Le immagini generate sono scarse nel rendere testo leggibile. Metti schermi, prezzi, passi e slogan nelle motion scene e tieni t2v_fast per il mondo reale.

Marchio

Un render API non rileva mai un marchio da solo, anche se il tuo account ha kit di marca. Scegli il marchio in ogni richiesta:

• brand_logo_url: il tuo logo, come URL https pubblico o URI dei dati.
• brand_colors: opzionale, fino a 12 colori esagonali, come ["#3B2416", "#F4E9DC"].

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

Senza un logo, il video viene visualizzato senza logo e senza scheda finale. Per dirlo esplicitamente, invia brand_enabled: false.

Kit di marca

brand_kit_id nomina uno dei tuoi kit di marca salvati. Per ora, invialo insieme a brand_logo_url. Un brand_kit_id da solo viene rifiutato con 422 BRAND_REQUIRED. Un kit che appartiene a un altro account non viene mai usato.

Foto del prodotto

product_image_url è una foto del tuo prodotto (un URL pubblico https o un URI dei dati). Mantiene il prodotto uguale in ogni scena, invece di lasciare che sia il modello a inventarne uno.

Alcuni formati vendono un prodotto e hanno bisogno di una foto. Se imposti un route del genere (ad esempio product-ad, unboxing, ugc-ad o app-demo) e il piano mostra il prodotto, un render senza foto viene rifiutato con 400 PRODUCT_IMAGE_REQUIRED. Per renderizzare senza una foto di proposito, invia product_enabled: false.

Presentatore

s2v e walk_talk scene mostrano una persona che parla. Serve un volto: avatar_preset_id per l’intero video, o ref_image_url sulla scena. Un piano con una scena di dialogo e senza volto viene rifiutato con 400 PRESENTER_REQUIRED. Per permettere Reigniter di usare un presentatore standard, invia presenter_enabled: false.

Niente che sostenga il video

Quando imposti un route e non invii brand, né foto di prodotto né presentatore, e il piano genererebbe tutte le sue immagini, il render viene rifiutato con 422 NO_ANCHOR. Senza un ancoraggio il modello inventa il prodotto e le persone, e loro non rispeccheranno il tuo brand.

Aggiungi uno dei tre, oppure manda comunque product_enabled: false o presenter_enabled: false a renderizzare.

I briefing sono pianificati prima di questi controlli

Con un brief, la pianificazione avviene prima e viene addebitata. Se la renderizzazione prevista viene poi rifiutata da uno degli assegni sopra, i crediti di pianificazione non vengono rimborsati. Invia al marchio, alla foto del prodotto o al presentatore con il brief, così che l’assegno venga approvato al primo intento.

Aspetto e suono

Campo	Valori	Predefinito
aspect	9:16, 16:9, 1:1, 4:5, 4:3, 3:4	9:16
quality	draft, standard, premium	draft
language	un codice linguistico, come 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	impostato dal formato
voice_preset_id	un ID vocale narratore	una voce predefinita
upscale	true o false	Definiti dal formato e dalla qualità

Più quality e upscale costano più crediti e richiedono più tempo.

Video di formazione

Imposta kind: "training" con un brief per pianificare un video di formazione invece di una pubblicità. Il planner scrive i passaggi e un riassunto, e usa motion scene per le istruzioni a schermo.

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

Ritenti e idempotenza

Invia un header Idempotency-Key con un valore unico, come un UUID, su ogni rendering. Se la tua richiesta scade e riprovi con la stessa chiave, Reigniter rifiuta la ripetizione e non renderizza né addebita una seconda volta.

• La ripetizione viene rifiutata, quindi non restituisce la job_id originale. Salva il job_id dalla prima risposta ogni volta che ne ricevi una.
• Con un scene_plan, la ripetizione restituisce 409 DUPLICATE_REQUEST.
• Con un brief, la ripetizione può restituire 402 con il messaggio This request was already submitted. Trattalo come un 409.
• Usa una nuova chiave per ogni nuovo video. Riutilizzare una chiave per un video diverso rifiuta quel video.

Senza l’intestazione di testa, ogni chiamata è una nuova renderizzazione e una nuova carica.

Filigrane

La risposta di rendering ha un campo watermarked. I video realizzati sul piano Agency non sono con filigrana.

Produzione

Quando il lavoro va bene, video_url su GET /v1/job/{id} è un collegamento diretto al MP4. Scaricalo e conserva la tua copia.