Pro API: genera video con audio

Un clip da un prompt, o l'animazione di un'immagine fissa che fornisci. Il file è un MP4, con audio quando lo richiedi.

Invia un video

POST /videos

{ "prompt": "a woman in a white linen dress walks along a beach at sunset, wind in her hair, she turns and smiles at the camera",
  "width": 1080, "height": 1920, "audio": true }

Frequenza fotogrammi predefinita: 30 fps. In precedenza i clip venivano renderizzati a 24 fps. Senza fps, un clip con la stessa length è quindi più breve di prima (241 fotogrammi: 8 s invece di 10 s). Invia "fps": 24 per mantenere il comportamento precedente.

La risposta:

{ "jobId": "...", "seed": 908172, "cost": 30 }

Il costo viene calcolato e comunicato al momento dell'invio, prima di qualsiasi addebito. Viene restituito anche il seed, che tu lo abbia indicato o sia stato estratto casualmente.

Formati e prezzo

Un video ha un prezzo per formato, come tariffa fissa indipendente dalla sua durata. Base: 5 crediti.

La tariffa fissa viene moltiplicata per 2 a 720p e per 3 a 1080p, e l'audio raddoppia il prezzo. I fattori si applicano alla tariffa base, non l'uno all'altro: 1080p con audio costa 5 x 3 x 2 = 30 crediti. Fino a 481 fotogrammi, cioè 20 s a 24 fps, la durata non cambia nulla (5 s o 20 s, stessa tariffa). Oltre 481 fotogrammi (fino a 721, solo con consistency enhanced, lunghezza fissa), il prezzo del formato viene raddoppiato. La frequenza fotogrammi (fps) non cambia il prezzo, ma i livelli contano i fotogrammi: a 30 fps, il prezzo normale vale fino a 16 s; a 60, fino a 8 s (12 s al doppio del prezzo in enhanced).

Un'eccezione: in Qualità, 480p senza audio costa 2 crediti, qualunque sia la sua durata (dall'11 ottobre 2026). Multi-Ref e la coerenza rafforzata mantengono la tariffa fissa del formato, 5 crediti.

La dimensione che ricevi. Il motore lavora in multipli di 32 e in due fasi, quindi il file viene restituito a 768 x 1280 (o 1280 x 768) per 720p e 1088 x 1920 (o 1920 x 1088) per 1080p. Il 480p rimane a 480 x 832 (o 832 x 480), eccetto nella coerenza rafforzata. Utile da sapere se vuoi unire o sovrapporre i nostri rendering.

Il canale turbo è stato ritirato l'11 ottobre 2026: una richiesta turbo viene renderizzata in Qualità 480p e fatturata di conseguenza (2 crediti senza audio, 10 con audio).

Conosci il prezzo prima di inviare

POST /videos/quote accetta lo stesso body di POST /videos ed esegue lo stesso calcolo, ma non viene creato nulla: nessun rendering, nessun credito bloccato, nessuna quota consumata. Chiamalo prima di confermare, in particolare da un agente che lavora con un budget.

{ "cost": 30, "mode": "ltx25", "format": "1080p", "audio": true, "fps": 30, "duration_auto": true,
  "seconds_max": 16, "detail": "flat 5 x 3 (1080p) x 2 (sound) = 30" }

detail illustra il calcolo; fps è la frequenza fotogrammi utilizzata e seconds_max la durata in secondi a quella frequenza. Con "consistency": "enhanced", il preventivo accetta una lunghezza fissa fino a 721 fotogrammi e applica la tariffa oltre 481 fotogrammi (x 2 (over 20 s) in detail a 24 fps, x 2 (over 481 frames) a un'altra frequenza). La stessa route esiste per le immagini, POST /images/quote, che risponde sempre { "cost": 1, ... }: un'immagine costa sempre 1 credito.

Per un clip Ultra fatturato al secondo, il preventivo indica la durata fatturata in seconds, e detail dettaglia il prezzo al secondo.

Polling, download, annullamento

Le stesse route delle immagini, sotto /videos.

• GET /videos/{jobId}: pending / completed / failed, stessi campi. Un'estensione rafforzata può terminare come failed con "error": "extension_not_applied" (il motore non ha ripreso la fine del clip precedente): non viene addebitato nulla, inviala di nuovo.
• GET /videos/{jobId}/file: l'MP4 (Content-Type: video/mp4).
• POST /videos/{jobId}/cancel: annulla, senza alcun addebito.

In Ultra fatturato al secondo, un rendering già in calcolo non si ferma più: l'annullamento risponde 409 render_in_progress, e il clip viene consegnato e fatturato. Un clip che il motore rifiuta in uscita termina in failed, con una frase in detail e il codice del motore in reason: non viene addebitato nulla.

Un video richiede da 1 a 5 minuti, più a lungo quando il motore parte da freddo. Esegui il polling ogni 3 secondi e scarica non appena lo stato è completed: il file non viene archiviato.

Più inquadrature in un solo clip

Un singolo prompt può contenere più inquadrature con tagli netti, fino a 20 secondi in totale a 24 fps (16 s a 30, il default). Descrivile in ordine: Shot 1: <inquadratura>, <azione>. Cut to Shot 2: .... Ripeti in ogni inquadratura tutto ciò che deve restare uguale (personaggio, outfit, luogo, luce), e concludi con una riga di mood condiviso.

Tralascia i timecode: lascia duration_auto attivo, e il motore sceglie la durata (fino a 20 s a 24 fps, 16 s a 30) e dove tagliare. Da due a quattro inquadrature per clip funziona meglio.

A cinematic sequence of three shots, same woman, same place, same lighting throughout.
Shot 1: Wide shot, night, light rain on a narrow Paris street with glowing café windows. A woman in a long beige trench coat walks toward the camera under a transparent umbrella, wet cobblestones reflecting warm yellow streetlights.
Cut to Shot 2: Close-up on her face under the umbrella, raindrops on the plastic, warm café light on her cheek, she smiles softly.
Cut to Shot 3: Medium shot from inside the café through the rainy window, she pushes the door open and steps in, warm light spilling onto the wet pavement.
Calm, melancholic, romantic mood.

Più inquadrature in un clip, o una sequenza? Servono a cose diverse:

Estendi un clip

Un clip può essere esteso: l'inquadratura successiva prosegue il movimento di quella precedente, senza interruzione al punto di giuntura. È guidata approssimativamente dall'ultimo secondo del clip precedente, non da un singolo fotogramma fermo. Aggiungi a POST /videos:

L'inquadratura estesa mantiene la risoluzione del clip precedente: width e height vengono ignorati con extend_job_id, e con extend_video la dimensione viene letta dal file che invii. Contiene solo i nuovi fotogrammi, quindi le inquadrature affiancate formano un video continuo. Mantiene la frequenza fotogrammi del clip precedente: ometti fps (la eredita) o indicane la stessa; un'altra viene rifiutata (extend_fps_mismatch). length è la durata nuova dell'inquadratura (121 = 5 s in più a 24 fps), ed è esatta: la durata automatica non si applica a un'estensione. Un'estensione costa il prezzo di un clip.

Limiti: nessun fotogramma finale o fotogramma chiave contemporaneamente, eccetto con la coerenza rafforzata.

L'audio prosegue al punto di giuntura. Con audio: true, quando la fine del clip precedente ha una traccia audio, la nuova inquadratura riprende quell'audio invece di generarne uno nuovo. Con extend_job_id, la fine ritagliata mantiene l'audio del clip; con extend_video, invia la fine con il suo audio. Senza una traccia audio in quella fine, nella coerenza rafforzata e in Ultra, l'audio riparte da zero con l'inquadratura: mantieni la stessa atmosfera in ogni prompt, così la giuntura si sente il meno possibile.

Estendi un clip poco dopo che è finito. Più tardi non è più disponibile per noi (clip_unavailable), e invii la sua fine tu stesso in extend_video.

Estendere un'inquadratura Ultra, in avanti o all'indietro

Un'inquadratura renderizzata in Ultra al secondo si estende anch'essa in Ultra, in avanti o all'indietro; qualsiasi altro clip si estende come sopra. Invia POST /videos con "quality": "max" e:

• Il rendering contiene solo la parte nuova, della durata di un clip Ultra (length / fps, 5 s con la durata automatica). Prende la risoluzione dell'inquadratura (width e height vengono ignorati) e si raccorda al suo ultimo fotogramma (forward) o al primo (backward).
• Niente immagine iniziale, riferimenti (multiref), movimento o coerenza rafforzata. backward non entra in una sequenza, che dispone le sue inquadrature una dopo l'altra.
• Prezzo: la parte nuova al prezzo Ultra al secondo, più, per ogni secondo dell'inquadratura estesa, 2 crediti in 480p, 5 in 720p e 13 in 1080p (ultra.extend_per_second in GET /pricing). Questi secondi si arrotondano al secondo superiore (con una precisione di 0,1 s) e si contano a 24 fotogrammi al secondo: un'inquadratura a frame rate più alto conta in proporzione (2 s a 60 fps contano come 5 s). POST /videos/quote con gli stessi campi restituisce extend_seconds e il prezzo esatto.
• Un'inquadratura di più di 24 ore: carica il suo file originale, così come consegnato da GET /videos/{jobId}/file. POST /extensions con { "size": <byte> } restituisce upload_id, upload_url, headers e expires_in (900 s); invia il file con PUT upload_url ed esattamente questi headers, poi passa extend_upload_id entro 2 ore. Un caricamento serve per un rendering: un MP4 da 4 a 30 s, al massimo 60 MB e 1080p. Prima del rendering, ogni video inviato alla modalità Ultra (un movimento o un video da prolungare) viene controllato, e non viene addebitato nulla se è rifiutato (400 input_video_out_of_limits): da 24 a 60 fotogrammi al secondo, un rapporto larghezza/altezza da 0,4 a 2,5 e, per un rendering, al massimo 30 s e 10 file per i video e i suoni di riferimento insieme. Con un volto realistico, un file ricodificato o rimontato viene rifiutato (400 engine_refused): passa solo l'originale. Un video che non è stato renderizzato in modalità Ultra (il render di un'altra modalità, per esempio) non viene prolungato in Ultra se mostra un volto realistico (400 extension_real_face, non viene addebitato nulla): prolungalo in modalità Qualità, oppure rifai l'inquadratura in Ultra.

Coerenza rafforzata

Con "consistency": "enhanced", il clip viene renderizzato da un canale che mantiene movimento, volti e sfondo più stabili nel tempo. Arriva fino a 721 fotogrammi per inquadratura, cioè 30 s a 24 fps e 24 s a 30 (length, lunghezza fissa) ed è pensato principalmente per video lunghi:

• Prima inquadratura: un clip normale (prompt, fotogramma iniziale, keyframes, end_image), fino a 721 fotogrammi.
• Estensione: extend_job_id (o extend_video) come in Estendi un clip, con la stessa consistency. length è ancora la durata nuova (fino a 721, cioè 30 s in più a 24 fps). Un'estensione rafforzata accetta anche keyframes, il cui at conta dal primo nuovo fotogramma, e un fotogramma finale end_image, impostato sull'ultimo fotogramma dell'inquadratura: ad esempio il fotogramma iniziale della prima inquadratura, per far ripetere in loop un video lungo.

Solo in modalità Qualità (mode ltx25, senza quality: "max"), fino a 1080p, non in Multi-Ref (400 consistency_mode). Prezzo: la tariffa fissa del formato (480p senza audio: 5 crediti) fino a 481 nuovi fotogrammi (20 s a 24 fps), raddoppiata oltre (vedi la tabella dei prezzi sopra). Frequenze fotogrammi: 24, 30, 50 o 60. Oltre 30, la lunghezza è fissa (fps_requires_fixed_duration altrimenti); 50 produce un leggero rallentatore (vedi fps). Il rendering richiede più tempo di un clip standard, e l'avvio può attendere una scheda grafica più potente (inquadrature lunghe). Una sequenza mantiene la stessa consistency per tutte le sue inquadrature. Dimensione restituita: la stessa della Qualità a 720p e 1080p; a 480p, il lato corto è 448 (448 x 832, 832 x 448, 448 x 448), poiché questo canale lavora in multipli di 64.

Alcuni prompt non sono ancora supportati. Per questi, una singola inquadratura di 20 s o meno (15 s con un end_image, a lunghezza fissa) viene renderizzata in consistenza standard, allo stesso prezzo. Oltre questo limite (length superiore a 481 con duration_auto: false, o superiore a 361 con un end_image), in un'estensione o in una sequenza, la richiesta viene rifiutata con 400 consistency_explicit: accorcia l'inquadratura o richiedi consistency: "standard".

Video lungo (sequenze)

Un clip dura al massimo 481 fotogrammi, cioè 20 s a 24 fps (721 con la coerenza rafforzata, 30 s a 24 fps). Per durate maggiori, una sequenza archivia ogni inquadratura al termine del suo rendering, poi le unisce in un unico MP4 senza ri-codifica. Un minuto, ad esempio, è 3 inquadrature da 20 s, o 2 da 30 s nella coerenza rafforzata, a 24 fps.

1. POST /sequences apre una sequenza e risponde { "sequence_id": "seq_...", ... }.
2. POST /videos con "sequence_id": "seq_..." per ogni inquadratura: la prima come al solito, le successive con extend_job_id impostato sull'inquadratura precedente. Ogni inquadratura viene archiviata nella sequenza, nell'ordine di invio, non appena GET /videos/{jobId} la vede completata.
3. POST /sequences/{id}/export una volta terminata l'ultima inquadratura. Risponde con seconds, resolution e file_url.
4. GET /sequences/{id}/file: il video assemblato (MP4).

In parallelo: GET /sequences/{id} fornisce lo stato (inquadrature archiviate o ancora attese), POST /sequences/{id}/clips con { "job_id": "..." } archivia un rendering manualmente, e DELETE /sequences/{id} elimina la sequenza immediatamente.

Regole. Ogni inquadratura ha la stessa risoluzione (le estensioni la mantengono) e la stessa scelta audio, tutte con audio o tutte silenziose, la stessa consistency e la stessa frequenza fotogrammi (fps): la prima inquadratura le imposta, e un'inquadratura diversa viene rifiutata (409 consistency_mismatch, 409 sequence_fps_mismatch; 422 encoding_mismatch per un'inquadratura archiviata manualmente). Un'inquadratura senza fps eredita quella della sequenza. Al massimo 30 inquadrature per sequenza e 5 sequenze in corso per licenza.

Cosa conserviamo e per quanto tempo. Le inquadrature di una sequenza in corso vengono cancellate 30 minuti dopo l'aggiunta dell'ultima, e il video assemblato 24 ore dopo l'esportazione. Dopodiché tutto viene eliminato.

Esportare la cartella del progetto

Una cartella di progetto riunisce in uno ZIP tutto ciò che serve per riprendere un video altrove o per automatizzarlo: le inquadrature, i loro riferimenti, il montaggio e un manifesto che permette di rigenerare ogni inquadratura. È gratuita: non viene generato nulla.

• POST /videos/{jobId}/export: un render di POST /videos (inquadratura singola, Multi-Ref, estensione).
• POST /sequences/{id}/project: tutte le inquadrature di una sequenza, una dopo l'altra.
• Corpo facoltativo, le stesse scelte della finestra di esportazione dell'app:
  • include_media (true di default): i video delle inquadrature e i loro originali firmati. false: nessun video (né clip, né originale, né film); le inquadrature conservano testo, impostazioni e riferimenti ("state": "expired") e il manifesto riporta videos_included: false.
  • include_references (true di default): le viste dei personaggi e le immagini degli elementi, in references/. false: nessuno viene copiato; nomi, @menzioni, id e impronte restano nel manifesto (references_included: false).
  • exclude_references: i riferimenti da non copiare, uno per uno, per id (character_id, subject_id), nome o @menzione, per esempio ["@Parc", "chr_..."] (200 al massimo). Il manifesto riporta references_included: "partial" e "included": false su ciascuno escluso (false se lo sono tutti). Una voce che non designa alcun riferimento dell'esportazione: 400 unknown_reference.
  • include_film (solo sequenza, false di default): il film di una sequenza già assemblata; richiede include_media (altrimenti 400 invalid_export_options, come un'opzione che non è un booleano o un exclude_references che non è una lista di testi).
  • manifest_only: true: solo il manifesto, senza ZIP.

La risposta è { "manifest": { ... }, "file_url": "...", "export_id": "exp_...", "expires_at": "...", "bytes": n }, e GET /exports/{id}/file scarica lo ZIP. Un'esportazione alla volta per licenza (409 export_in_progress), 2 GB al massimo (413 export_too_large: esporta le inquadrature una per una).

Cosa conserviamo e per quanto tempo. Per ogni POST /videos accettato, il server conserva una scheda del render senza alcuna immagine né video: il testo, le impostazioni, gli identificativi (un'immagine inviata in base64 lascia solo la sua impronta). Viene cancellata 24 ore dopo l'invio; oltre, l'esportazione risponde 404 unknown_export. Lo ZIP viene cancellato 45 minuti dopo il primo download, al massimo 2 ore dopo la sua creazione. Un'inquadratura che il server non ha più esce come "state": "expired", senza il file ma con il testo, le impostazioni e i riferimenti: un agente può rigenerarla con api_request.

Sequenza. L'assemblaggio cancella le inquadrature una per una. Per avere le inquadrature e il film, esporta il progetto prima di assemblare, poi assembla ed esporta di nuovo con { "include_film": true }: il film si aggiunge, e le inquadrature escono allora come expired.

Modalità Ultra

La modalità Ultra è il rendering video più fine. Aggiungi "quality": "max" a POST /videos (con mode ltx25, il valore predefinito). Si fattura al secondo, oppure a prezzo fisso con un LoRA o in un'estensione di un clip non renderizzato al secondo; estendere un'inquadratura Ultra, in avanti o all'indietro, si fattura al secondo. POST /videos/quote indica il prezzo esatto della tua richiesta.

Al secondo

Il clip è fatturato al secondo in base alla risoluzione, audio incluso:

• Durata: da 4 a 30 s a 24 fotogrammi al secondo, nota prima del rendering: 5 s con la durata automatica (duration_auto, predefinita), altrimenti length / fps (24 se fps manca), arrotondata al secondo.
• Formato: quello richiesto, al rapporto più vicino; il 480p è renderizzato in 480p. Oltre il 1080p: resolution_outside_ultra.
• Immagine iniziale (image): possibile. Il motore può rifiutare un testo o un'immagine all'invio: 400 engine_refused, con il motivo in detail e il codice in code; non viene addebitato nulla.
• Nessun seed: seed viene ignorato e la risposta non lo riporta.
• Annullamento: libero finché il rendering attende il suo turno; una volta in calcolo, 409 render_in_progress, e il clip viene consegnato e fatturato.
• Nessuna immagine finale, nessun fotogramma chiave e nessuna coerenza rafforzata in Ultra.

A prezzo fisso

Con un LoRA o in un'estensione di un clip non renderizzato al secondo, Ultra è renderizzato con il modello video completo, a prezzo fisso:

Il prezzo è fisso per formato: audio e durata non cambiano nulla. Ultra parte da 720p: una richiesta 480p viene renderizzata, e fatturata, in 720p. POST /videos/quote fornisce il prezzo esatto. 1080p (1920 x 1088) è il massimo, in ogni modalità: il 4K non è più offerto. Una dimensione maggiore viene rifiutata (ultra_4k_unavailable con quality: "max", resolution_above_quality senza).

• Durata: al massimo 481 fotogrammi, come qualsiasi clip (20 s a 24 fps, 16 s a 30, 8 s a 60). Le estensioni e i video lunghi funzionano anche in Ultra. Un'estensione mantiene la dimensione del clip che prosegue, e sotto 720p viene fatturata al prezzo 720p.
• Tempo: diversi minuti per un clip da 5 s, di più per un clip da 20 s. L'avvio può attendere che una scheda grafica potente si liberi.
• Nessuna transizione (end_image) in Ultra (ultra_incompatible).
• Nessun fotogramma chiave (keyframes) in Ultra (keyframes_mode).
• Un LoRA del personaggio del tuo account si applica in Ultra come nella modalità normale.

Multi-Ref Video

Un clip in cui recitano da 1 a 4 personaggi (fino a 12 in Ultra), ognuno riconoscibile, in una location opzionale, con oggetti salvati, animali e una location salvata quando ne hai bisogno. I personaggi provengono da GET /characters: creati da una foto tramite API, o nell'app. Gli oggetti, gli animali e le location provengono da GET /subjects. Aggiungi l'oggetto multiref a POST /videos (permesso videos) e chiama ogni personaggio con @Nome nel prompt:

{
  "prompt": "@Lea walks toward @Tom in a sunny kitchen and hands him a cup. Sound: footsteps, soft music.",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Lea", "description": "a 28 year old woman with long red hair" },
      { "character_id": "chr_21bc...", "name": "Tom", "description": "a 30 year old man", "strength": 1.2 }
    ],
    "background_b64": "<optional: an image of the location>",
    "background_description": "a sunny kitchen"
  },
  "width": 1088, "height": 1920,
  "audio": true
}

• Prompt in inglese, un paragrafo al presente; Sound: per l'audio, le battute di dialogo tra virgolette, exactly 2 people e dove si trova ognuno quando è utile, nessuna negazione. Una creatura viene descritta per quello che è. Un @Nome che non corrisponde a nessun personaggio viene rifiutato (unknown_mention).
• Formati (width x height): verticale 480 x 832, 720 x 1280, 1088 x 1920; orizzontale 832 x 480, 1280 x 720, 1920 x 1088; quadrato 480 x 480, 720 x 720, 1088 x 1088. Nessun 4K; 480p solo in Qualità.
• Modalità: Qualità (il default), o Ultra (quality: "max"). Nessuna estensione e nessuna transizione.
• Durata: automatica (duration_auto, il default), o fissa con duration_auto: false e length 121 (5 s), 241 (10 s) o 481 (20 s) a 24 fps; a un'altra frequenza, le stesse durate contate in fotogrammi, al massimo 481 (a 30: 145, 297, 481; a 60: 297, 481).
• Frequenza fotogrammi: fps 24, 30 (il default) o 60, come per qualsiasi clip; length conta i fotogrammi a questa frequenza, al massimo 481 (16 s a 30, 8 s a 60).
• Prezzo: il prezzo di un clip. In Qualità, la tariffa fissa del formato nella tabella sopra, raddoppiata con audio; 480p senza audio rimane a 5 crediti (il prezzo ridotto della Qualità non si applica al Multi-Ref). POST /videos/quote con "multiref": true fornisce il prezzo esatto.
• Il server adatta le inquadrature al formato esatto del video: invia i personaggi così come sono. Un personaggio che ha solo una vista viene renderizzato, con warnings limited_likeness nella risposta: la somiglianza è limitata.
• Voci del profilo: con l'audio, characters[0] e characters[1] parlano per default con la voce del loro profilo quando è online (has_voice); voice generated lascia che il modello ne crei una. La risposta indica la voce di ciascuno in voices (character_id, voice: character, custom o generated).
• Voci dei personaggi (voice_b64): il modello fa parlare il personaggio con quella voce, labbra incluse; il server usa i primi 5 secondi. Al massimo due voci, su characters[0] e characters[1] (il motore supporta 2 voci). Ordina characters come il dialogo: characters[0] parla per primo, characters[1] risponde. Richiede audio ("audio": true), altrimenti voice_requires_audio; una voce su un altro personaggio: voice_slot; un file illeggibile: unsupported_audio_format; oltre 4 MB: audio_too_large. Solo i primi 5 secondi vengono usati: invia un breve estratto. L'intero body della richiesta deve restare sotto 30 MB (oltre, un 413 senza body JSON). Nessun costo aggiuntivo.
• Polling, download e annullamento sono quelli di qualsiasi video (vedi Polling, download, annullamento, sopra).

Oggetti, animali e location salvati. Altri due campi di multiref assegnano i soggetti che hai salvato dalle tue immagini:

name assume per default la prima parola del nome del soggetto, e ogni @Nome nel prompt viene abbinato come quello di un personaggio. Una location passata in subjects, o un oggetto passato come location, viene rifiutato (invalid_subject_type). Il prezzo non cambia: è il prezzo di un clip. Un soggetto viene usato con le sue prime 5 immagini (tutte in Ultra, al massimo 6).

"multiref": {
  "characters": [{ "character_id": "chr_8f3a...", "name": "Lea" }],
  "subjects": [{ "subject_id": "sub_1c2d...", "name": "Rex" }],
  "location": { "subject_id": "sub_9e8f...", "name": "Loft" }
},
"prompt": "@Lea throws a ball to @Rex across @Loft. Sound: barking, laughter."

In Ultra, un clip Multi-Ref segue le regole di Ultra fatturato al secondo: stesso prezzo al secondo, audio incluso, da 4 a 30 s a 24 fotogrammi al secondo (5 s con la durata automatica), da 480p a 1080p, nessun seed.

• Ogni personaggio parte con la sua character sheet (o, se non ce l'ha, con tutte le sue immagini), e il server riunisce tutto in un'unica immagine; ogni oggetto, animale o ambientazione con tutte le sue immagini (al massimo 6).
• Il primo rendering di un personaggio prepara questa immagine, qualche decina di secondi in più: il suo jobId inizia allora con sdp- e si segue come gli altri.
• Nessuna voce: voice_b64 e la voce della scheda vengono ignorate (warnings voice_ignored), e strength non ha effetto.
• Il motore può rifiutare un'immagine di riferimento (un volto reale, per esempio): il rendering termina in failed con il motivo, e non viene addebitato nulla.

Stili, outfit e movimento. Solo in Ultra (quality: "max"), tre campi in più di multiref; altrove la richiesta viene rifiutata (multiref_ultra_only), mai renderizzata senza di essi.

• Al massimo 30 immagini in Ultra, tra personaggi, soggetti, stili, outfit e ambientazione (multiref_too_many_images), di cui al massimo 12 personaggi (multiref_characters_required oltre). Se ne consigliano 8: da 9 a 12, il render viene elaborato con warnings many_characters, perché alcuni possono mancare o mescolarsi. Uno stile fuori da styles, o un outfit fuori da outfits, viene rifiutato (invalid_subject_type).
• Prezzo del movimento: 3 crediti al secondo del video di movimento (arrotondato al secondo superiore), in aggiunta al rendering, indicati in GET /pricing (ultra.motion_per_second); POST /videos/quote con lo stesso multiref.motion restituisce motion_seconds e il prezzo esatto.
• Caricamento diretto, per un video di movimento pesante: POST /motions con { "size": <byte> } (al massimo 20 MB) restituisce motion_id, upload_url, headers e expires_in (900 s); invia il file con PUT upload_url ed esattamente questi headers, poi passa multiref.motion.motion_id a POST /videos entro 2 ore. Un motion_id serve per un rendering.

"quality": "max",
"multiref": {
  "characters": [{ "character_id": "chr_8f3a...", "name": "Lea" }],
  "styles": [{ "subject_id": "sub_a1b2..." }],
  "outfits": [{ "subject_id": "sub_c3d4...", "name": "RedGown", "worn_by": "Lea" }],
  "motion": { "motion_id": "4f0c2a9b1d7e6a35", "description": "a low tracking shot from the side" }
},
"prompt": "@Lea walks along a seaside promenade at sunset."

I codici di errore di stili, outfit e movimento sono in Limiti ed errori.

Con il server MCP, l'agente fa tutto questo con tendre_multiref_video: descrivi la scena e nomina i personaggi, gli oggetti, gli animali e la location (subjects, location_id).

Face swap

La persona filmata nel tuo video diventa uno dei tuoi personaggi: viso, capelli, corpo e outfit (o solo la testa, vedi part), mantenendo i suoi gesti, le sue labbra e l'ambientazione, e la sua voce a meno che il personaggio non abbia la propria (vedi voice). È il Face swap dell'app, su un passaggio di al massimo 20 s: un personaggio, senza concatenazione e senza transizione. La richiesta è POST /faceswap (permesso videos):

{
  "video_b64": "<the video in base64: MP4, MOV, WebM or MKV, 20 MB at most>",
  "character_id": "chr_8f3a...",
  "start": 2,
  "duration": 6,
  "scene": "@Lea wears a long red coat.",
  "zone": "normal",
  "likeness": 1
}

Video e voce insieme: al massimo 22 MB, in modo che il body della richiesta rimanga sotto 30 MB (oltre, un 413 senza body JSON).

• Il server prepara tutto. Ritaglia il passaggio, lo porta alla frequenza fotogrammi di lavoro (30 fps per una sorgente a 29 fps o più, 50 e 60 inclusi, 24 al di sotto) e al formato di lavoro (multipli di 128, lato corto di 768, il rapporto più vicino al tuo video), e adatta le viste del personaggio a quel formato.
• Quello che ricevi è il video del passaggio nel formato di lavoro, circa un megapixel (768 x 1408 per un video verticale, ad esempio), con le proporzioni del tuo video entro il 5%. La risoluzione completa e più personaggi in sequenza restano specifici dell'app desktop tendre.AI: incolla il personaggio sul video originale alla sua piena risoluzione e concatena più personaggi.
• Prezzo: 6 crediti per secondo del passaggio preparato (seconds nella risposta), arrotondato al credito successivo. La risposta fornisce jobId, seed, cost e il passaggio preparato (width, height, length, fps, seconds, audio, voice, views, part). Un personaggio che ha solo una vista viene renderizzato, con warnings limited_likeness.
• Nessun preventivo: né POST /videos/quote né il tendre_quote dell'MCP supportano il Face swap. Per calcolare il prezzo prima di inviare, leggi grid.body_swap in GET /pricing: secondi del passaggio x per_block_720p (il prezzo di un blocco) / block_seconds (la durata di un blocco), arrotondato al credito successivo.
• Alcune scene vengono renderizzate dai tre ritratti del personaggio ritagliati alla testa (heads_only nella risposta), e l'outfit delle sue viste non viene più imposto: è la scena a decidere.
• Un Face swap conta come un utilizzo del personaggio e posticipa la sua cancellazione, come il Multi-Ref.
• Polling, download e annullamento sono quelli di qualsiasi video (vedi Polling, download, annullamento, sopra): GET /videos/{jobId}, GET /videos/{jobId}/file, POST /videos/{jobId}/cancel.
• Errori specifici: video_required, video_too_large, unreadable_video, invalid_start, passage_too_short, invalid_duration, invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part, invalid_voice_choice, character_required, unknown_character, audio_too_large (una voce oltre 2 MB), face_swap_too_large (il passaggio è ancora troppo pesante dopo la preparazione: accorcia duration), server_busy (due video sono già in preparazione: riprova dopo Retry-After, 20 s), face_swap_unavailable e face_swap_price_missing (Face swap chiuso, o senza un prezzo: riprova più tardi). Il significato di ognuno: Limiti ed errori.
• Il tuo video transita attraverso i nostri server durante la preparazione, poi viene inviato alla scheda grafica che lo renderizza, come qualsiasi immagine sorgente.

Usa solo video di persone che hanno dato il loro consenso: è una regola dei termini d'uso.

Con il server MCP, l'agente fa tutto questo con tendre_face_swap.