Pro API: generowanie wideo z dźwiękiem

Klip z promptu lub animacja dostarczonego przez ciebie nieruchomego obrazu. Plik to MP4, z dźwiękiem gdy tego zażądasz.

Prześlij wideo

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 }

Domyślna liczba klatek: 30 fps. Wcześniej klipy były renderowane przy 24 fps. Bez fps klip o tej samej wartości length jest zatem krótszy niż poprzednio (241 klatek: 8 s zamiast 10 s). Wyślij "fps": 24, aby zachować poprzednie zachowanie.

Odpowiedź:

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

Koszt jest obliczany i podawany przy przesyłaniu, zanim cokolwiek zostanie naliczone. seed jest również zwracany, niezależnie od tego, czy go podałeś, czy został wylosowany.

Formaty i cena

Wideo jest rozliczane według formatu, jako stała stawka niezależna od jego długości. Podstawa: 5 kredytów.

Stała stawka jest mnożona przez 2 przy 720p i przez 3 przy 1080p, a następnie dźwięk podwaja cenę. Współczynniki stosuje się do stawki podstawowej, nie do siebie nawzajem: 1080p z dźwiękiem kosztuje 5 x 3 x 2 = 30 kredytów. Do 481 klatek, czyli 20 s przy 24 fps, długość nic nie zmienia (5 s lub 20 s, ta sama stawka). Powyżej 481 klatek (do 721, tylko przy consistency enhanced, stała długość), cena formatu jest podwajana. Liczba klatek (fps) nie zmienia ceny, ale progi liczą klatki: przy 30 fps normalna cena obowiązuje do 16 s; przy 60 do 8 s (12 s przy podwójnej cenie w enhanced).

Jeden wyjątek: w trybie Jakość, 480p bez dźwięku kosztuje 2 kredytów, niezależnie od jego długości (od 11 października 2026). Multi-Ref i wzmocniona spójność zachowują stałą stawkę formatu, 5 kredytów.

Rozmiar, który otrzymujesz. Silnik pracuje w wielokrotnościach 32 i w dwóch etapach, więc plik wychodzi w rozmiarze 768 x 1280 (lub 1280 x 768) dla 720p i 1088 x 1920 (lub 1920 x 1088) dla 1080p. 480p pozostaje przy 480 x 832 (lub 832 x 480), z wyjątkiem wzmocnionej spójności. Warto wiedzieć, jeśli łączysz lub nakładasz nasze rendery.

Tor turbo został wycofany 11 października 2026: żądanie turbo jest renderowane w trybie Jakość 480p i rozliczane jak ono (2 kredytów bez dźwięku, 10 z dźwiękiem).

Poznaj cenę przed przesłaniem

POST /videos/quote przyjmuje tę samą treść co POST /videos i wykonuje to samo obliczenie, ale nic nie jest tworzone: brak renderowania, brak zatrzymanych kredytów, brak zużytego limitu. Wywołaj go przed podjęciem decyzji, szczególnie z agenta działającego w ramach budżetu.

{ "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 wyjaśnia obliczenie; fps to użyta liczba klatek, a seconds_max to długość w sekundach przy tym tempie. Przy "consistency": "enhanced" wycena przyjmuje stałą długość do 721 klatek i stosuje stawkę powyżej 481 klatek (x 2 (over 20 s) w detail przy 24 fps, x 2 (over 481 frames) przy innym tempie). Ta sama trasa istnieje dla obrazów, POST /images/quote, która zawsze odpowiada { "cost": 1, ... }: obraz zawsze kosztuje 1 kredyt.

Dla klipu Ultra rozliczanego za sekundę wycena podaje rozliczaną długość w seconds, a detail rozpisuje cenę za sekundę.

Odpytywanie, pobieranie, anulowanie

Te same trasy co obrazy, pod /videos.

• GET /videos/{jobId}: pending / completed / failed, te same pola. Rozszerzone ujęcie ze wzmocnioną spójnością może zakończyć się jako failed z "error": "extension_not_applied" (silnik nie przejął końca poprzedniego klipu): nic nie jest naliczane, prześlij ponownie.
• GET /videos/{jobId}/file: plik MP4 (Content-Type: video/mp4).
• POST /videos/{jobId}/cancel: anuluje i nic nie jest naliczane.

W Ultra rozliczanym za sekundę render, który jest już liczony, nie zatrzymuje się: anulowanie odpowiada 409 render_in_progress, a klip zostaje dostarczony i rozliczony. Klip odrzucony przez silnik na wyjściu kończy się jako failed, ze zdaniem w detail i kodem silnika w reason: nic nie jest naliczane.

Wideo zajmuje od 1 do 5 minut, dłużej gdy silnik uruchamia się po raz pierwszy. Odpytuj co 3 sekundy i pobieraj natychmiast po tym, gdy status zmieni się na completed: plik nie jest archiwizowany.

Kilka ujęć w jednym klipie

Jeden prompt może zawierać kilka ujęć z twardymi cięciami, łącznie do 20 sekund przy 24 fps (16 s przy 30, domyślnie). Opisz je po kolei: Shot 1: <kadrowanie>, <akcja>. Cut to Shot 2: .... Powtarzaj w każdym ujęciu to, co ma pozostać niezmienne (postać, strój, miejsce, światło) i zakończ jedną linią wspólnego nastroju.

Pomiń timekody: zostaw włączone duration_auto, a silnik dobierze długość (do 20 s przy 24 fps, 16 s przy 30) i miejsce cięcia. Najlepiej sprawdzają się od dwóch do czterech ujęć na klip.

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.

Kilka ujęć w jednym klipie lub sekwencja? Służą różnym celom:

Rozszerzanie klipu

Klip można rozszerzyć: następne ujęcie kontynuuje ruch poprzedniego bez zatrzymania w miejscu łączenia. Prowadzone jest przez mniej więcej ostatnią sekundę poprzedniego klipu, a nie przez pojedynczą nieruchomą klatkę. Dodaj do POST /videos:

Rozszerzone ujęcie zachowuje rozdzielczość poprzedniego klipu: width i height są ignorowane przy extend_job_id, a przy extend_video rozmiar jest odczytywany z przesłanego pliku. Zawiera tylko nowe klatki, więc ujęcia ułożone jedno za drugim tworzą jedno ciągłe wideo. Zachowuje tempo klatek poprzedniego klipu: pomiń fps (zostanie przejęte) lub podaj to samo; inne jest odrzucane (extend_fps_mismatch). length to nowy czas trwania ujęcia (121 = 5 s więcej przy 24 fps) i jest dokładne: automatyczna długość nie ma zastosowania do rozszerzenia. Rozszerzenie kosztuje tyle co klip.

Ograniczenia: nie można jednocześnie używać klatki końcowej ani klatek kluczowych, z wyjątkiem wzmocnionej spójności.

Dźwięk kontynuuje się w miejscu łączenia. Przy audio: true, gdy koniec poprzedniego klipu ma ścieżkę dźwiękową, nowe ujęcie przejmuje ten dźwięk zamiast generować nowy. Przy extend_job_id obcięty koniec zachowuje dźwięk klipu; przy extend_video wyślij koniec razem z jego dźwiękiem. Bez ścieżki dźwiękowej na tym końcu, w wzmocnionej spójności i w Ultra, dźwięk zaczyna się od nowa wraz z ujęciem: trzymaj tę samą atmosferę w każdym prompcie, żeby łączenie było jak najmniej słyszalne.

Rozszerzaj klip wkrótce po jego zakończeniu. Później nie jest już dla nas dostępny (clip_unavailable), a wtedy sam przesyłasz jego koniec w extend_video.

Rozszerzanie ujęcia Ultra, do przodu lub do tyłu

Ujęcie wyrenderowane w Ultra za sekundę również rozszerza się w Ultra, do przodu lub do tyłu; każdy inny klip rozszerza się jak wyżej. Wyślij POST /videos z "quality": "max" oraz:

• Render zawiera tylko nową część, o długości klipu Ultra (length / fps, 5 s przy automatycznej długości). Przyjmuje rozdzielczość ujęcia (width i height są ignorowane) i łączy się z jego ostatnią klatką (forward) lub pierwszą (backward).
• Bez obrazu startowego, referencji (multiref), ruchu i wzmocnionej spójności. backward nie trafia do sekwencji, która układa swoje ujęcia jedno po drugim.
• Cena: nowa część po cenie Ultra za sekundę, plus za każdą sekundę rozszerzanego ujęcia 2 kredytów w 480p, 5 w 720p i 13 w 1080p (ultra.extend_per_second w GET /pricing). Te sekundy zaokrągla się w górę do pełnej sekundy (z dokładnością do 0,1 s) i liczy przy 24 klatkach na sekundę: ujęcie o wyższej liczbie klatek liczy się proporcjonalnie (2 s przy 60 fps liczą się jak 5 s). POST /videos/quote z tymi samymi polami zwraca extend_seconds i dokładną cenę.
• Ujęcie starsze niż 24 godziny: prześlij jego oryginalny plik, taki, jaki dostarczył GET /videos/{jobId}/file. POST /extensions z { "size": <bajty> } zwraca upload_id, upload_url, headers i expires_in (900 s); wyślij plik przez PUT upload_url dokładnie z tymi headers, a następnie przekaż extend_upload_id w ciągu 2 godzin. Jedno przesłanie służy do jednego renderu: MP4 od 4 do 30 s, najwyżej 60 MB i 1080p. Przed renderem każde wideo wysyłane do trybu Ultra (ruch lub wideo do przedłużenia) jest sprawdzane, a przy odrzuceniu nic nie jest pobierane (400 input_video_out_of_limits): od 24 do 60 klatek na sekundę, proporcja szerokości do wysokości od 0,4 do 2,5 oraz na jeden render najwyżej 30 s i 10 plików łącznie dla wideo i dźwięków referencyjnych. Przy realistycznej twarzy plik przekodowany lub zmontowany jest odrzucany (400 engine_refused): przechodzi tylko oryginał. Wideo, którego nie wyrenderował tryb Ultra (na przykład render z innego trybu), nie jest przedłużane w Ultra, gdy pokazuje realistyczną twarz (400 extension_real_face, nic nie jest naliczane): przedłuż je w trybie Jakość albo wykonaj ujęcie ponownie w Ultra.

Wzmocniona spójność

Przy "consistency": "enhanced" klip jest renderowany przez tor, który utrzymuje ruch, twarze i tło stabilniejsze w czasie. Obsługuje do 721 klatek na ujęcie, czyli 30 s przy 24 fps i 24 s przy 30 (length, stała długość) i jest przeznaczony głównie do długich wideo:

• Pierwsze ujęcie: normalny klip (prompt, klatka startowa, keyframes, end_image), do 721 klatek.
• Rozszerzenie: extend_job_id (lub extend_video) jak w Rozszerzaniu klipu, z tym samym consistency. length to nadal nowy czas trwania (do 721, czyli 30 s więcej przy 24 fps). Rozszerzone ujęcie ze wzmocnioną spójnością przyjmuje też keyframes, których at liczy od pierwszej nowej klatki, oraz klatkę końcową end_image, ustawioną na ostatniej klatce ujęcia: na przykład klatkę startową pierwszego ujęcia, żeby długie wideo zapętlało się.

Tylko tryb Jakość (mode ltx25, bez quality: "max"), do 1080p, nie w Multi-Ref (400 consistency_mode). Cena: stała stawka formatu (480p bez dźwięku: 5 kredytów) do 481 nowych klatek (20 s przy 24 fps), podwojona powyżej (patrz cennik powyżej). Liczby klatek: 24, 30, 50 lub 60. Powyżej 30 długość jest stała (fps_requires_fixed_duration w przeciwnym razie); 50 daje lekkie spowolnienie (patrz fps). Renderowanie trwa dłużej niż standardowy klip, a jego start może czekać na większą kartę graficzną (długie ujęcia). Sekwencja zachowuje tę samą consistency dla wszystkich ujęć. Dostarczany rozmiar: taki sam jak w trybie Jakość przy 720p i 1080p; przy 480p krótszy bok wychodzi 448 (448 x 832, 832 x 448, 448 x 448), ponieważ ten tor pracuje w wielokrotnościach 64.

Niektóre prompty nie są jeszcze obsługiwane. Dla nich pojedyncze ujęcie o długości do 20 s (15 s z end_image, przy stałej długości) jest renderowane ze standardową spójnością, w tej samej cenie. Powyżej tego (length powyżej 481 przy duration_auto: false, lub powyżej 361 z end_image), w rozszerzeniu lub w sekwencji, żądanie jest odrzucane z 400 consistency_explicit: skróć ujęcie lub użyj consistency: "standard".

Długie wideo (sekwencje)

Klip trwa najwyżej 481 klatek, czyli 20 s przy 24 fps (721 przy wzmocnionej spójności, 30 s przy 24 fps). Dla dłuższych treści sekwencja zapisuje każde ujęcie po zakończeniu jego renderowania, a następnie łączy je w jeden plik MP4 bez ponownego kodowania. Minuta to na przykład 3 ujęcia po 20 s lub 2 ujęcia po 30 s przy wzmocnionej spójności, przy 24 fps.

1. POST /sequences otwiera sekwencję i odpowiada { "sequence_id": "seq_...", ... }.
2. POST /videos z "sequence_id": "seq_..." dla każdego ujęcia: pierwsze jak zwykle, kolejne z extend_job_id ustawionym na poprzednie ujęcie. Każde ujęcie jest zapisywane w sekwencji, w kolejności przesyłania, gdy tylko GET /videos/{jobId} pokaże jego zakończenie.
3. POST /sequences/{id}/export gdy ostatnie ujęcie jest gotowe. Odpowiada z seconds, resolution i file_url.
4. GET /sequences/{id}/file: zmontowane wideo (MP4).

Obok tego: GET /sequences/{id} podaje stan (zapisane lub oczekiwane ujęcia), POST /sequences/{id}/clips z { "job_id": "..." } ręcznie zapisuje render, a DELETE /sequences/{id} natychmiast usuwa sekwencję.

Zasady. Każde ujęcie ma tę samą rozdzielczość (rozszerzenia ją zachowują) i ten sam wybór dźwięku, wszystkie z dźwiękiem lub wszystkie bez, tę samą consistency i tę samą liczbę klatek (fps): pierwsze ujęcie je ustawia, a ujęcie różniące się jest odrzucane (409 consistency_mismatch, 409 sequence_fps_mismatch; 422 encoding_mismatch dla ujęcia zapisanego ręcznie). Ujęcie bez fps przyjmuje tempo sekwencji. Najwyżej 30 ujęć na sekwencję i 5 sekwencji w toku na licencję.

Co przechowujemy i jak długo. Ujęcia sekwencji w toku są usuwane 30 minut po dodaniu ostatniego, a zmontowane wideo 24 godziny po eksporcie. Potem wszystko znika.

Eksport folderu projektu

Folder projektu zbiera w jednym ZIP-ie wszystko, czego potrzeba, by kontynuować pracę nad wideo gdzie indziej albo ją zautomatyzować: ujęcia, ich referencje, montaż i manifest, który pozwala ponownie wyrenderować każde ujęcie. Jest darmowy: nic nie jest renderowane.

• POST /videos/{jobId}/export: jeden render z POST /videos (pojedyncze ujęcie, Multi-Ref, przedłużenie).
• POST /sequences/{id}/project: wszystkie ujęcia sekwencji, jedno po drugim.
• Opcjonalna treść, te same wybory co w oknie eksportu aplikacji:
  • include_media (domyślnie true): filmy ujęć i ich podpisane oryginały. false: żadnego filmu (ani klipu, ani oryginału, ani filmu sekwencji); ujęcia zachowują tekst, ustawienia i referencje ("state": "expired"), a manifest zawiera videos_included: false.
  • include_references (domyślnie true): widoki postaci i obrazy elementów, w references/. false: żadna nie jest kopiowana; ich nazwy, @wzmianki, id i odciski zostają w manifeście (references_included: false).
  • exclude_references: referencje, których nie kopiować, pojedynczo, po id (character_id, subject_id), nazwie lub @wzmiance, na przykład ["@Parc", "chr_..."] (najwyżej 200). Manifest zawiera references_included: "partial" i "included": false przy każdej pominiętej (false, jeśli pominięto wszystkie). Pozycja, która nie wskazuje żadnej referencji eksportu: 400 unknown_reference.
  • include_film (tylko sekwencja, domyślnie false): film już zmontowanej sekwencji; wymaga include_media (inaczej 400 invalid_export_options, tak jak opcja, która nie jest wartością logiczną, lub exclude_references, które nie jest listą tekstów).
  • manifest_only: true: sam manifest, bez ZIP-a.

Odpowiedź to { "manifest": { ... }, "file_url": "...", "export_id": "exp_...", "expires_at": "...", "bytes": n }, a GET /exports/{id}/file pobiera ZIP. Jeden eksport naraz na licencję (409 export_in_progress), najwyżej 2 GB (413 export_too_large: eksportuj ujęcia pojedynczo).

Co przechowujemy i jak długo. Dla każdego przyjętego POST /videos serwer zachowuje kartę renderu bez żadnego obrazu ani wideo: tekst, ustawienia, identyfikatory (obraz wysłany w base64 zostawia tylko swój odcisk). Jest usuwana 24 godziny po wysłaniu; później eksport odpowiada 404 unknown_export. ZIP jest usuwany 45 minut po pierwszym pobraniu, najpóźniej 2 godziny po utworzeniu. Ujęcie, którego serwer już nie ma, wychodzi jako "state": "expired", bez pliku, ale z tekstem, ustawieniami i referencjami: agent może je ponownie wyrenderować za pomocą api_request.

Sekwencja. Montaż usuwa ujęcia jedno po drugim. Aby mieć ujęcia i film, wyeksportuj projekt przed montażem, potem zmontuj i wyeksportuj ponownie z { "include_film": true }: film zostanie dodany, a ujęcia wyjdą wtedy jako expired.

Tryb Ultra

Tryb Ultra to najdokładniejszy render wideo. Dodaj "quality": "max" do POST /videos (z mode ltx25, wartością domyślną). Jest rozliczany za sekundę albo po stałej cenie z LoRA lub przy rozszerzeniu klipu, który nie był renderowany za sekundę; rozszerzenie ujęcia Ultra, do przodu lub do tyłu, jest rozliczane za sekundę. POST /videos/quote podaje dokładną cenę twojego zlecenia.

Za sekundę

Klip jest rozliczany za sekundę według rozdzielczości, z dźwiękiem w cenie:

• Długość: od 4 do 30 s przy 24 klatkach na sekundę, znana przed renderem: 5 s przy długości automatycznej (duration_auto, domyślnie), w przeciwnym razie length / fps (24, gdy brak fps), zaokrąglona do sekundy.
• Format: ten zamówiony, w najbliższych proporcjach; 480p jest renderowane w 480p. Powyżej 1080p: resolution_outside_ultra.
• Obraz startowy (image): możliwy. Silnik może odrzucić tekst lub obraz przy wysyłce: 400 engine_refused, z powodem w detail i kodem w code; nic nie jest naliczane.
• Bez ziarna: seed jest ignorowane, a odpowiedź go nie podaje.
• Anulowanie: bezpłatne, dopóki render czeka na swoją kolej; gdy jest już liczony, 409 render_in_progress, a klip zostaje dostarczony i rozliczony.
• W Ultra nie ma obrazu końcowego, klatek kluczowych ani wzmocnionej spójności.

Po stałej cenie

Z LoRA lub przy rozszerzeniu klipu, który nie był renderowany za sekundę, Ultra jest renderowane pełnym modelem wideo, po stałej cenie:

Cena jest stała na format: dźwięk i długość nic nie zmieniają. Ultra zaczyna od 720p: żądanie 480p jest renderowane i rozliczane w 720p. POST /videos/quote podaje dokładną cenę. 1080p (1920 x 1088) to maksimum, w każdym trybie: 4K nie jest już oferowane. Większy rozmiar jest odrzucany (ultra_4k_unavailable z quality: "max", resolution_above_quality bez niego).

• Długość: najwyżej 481 klatek, jak każdy klip (20 s przy 24 fps, 16 s przy 30, 8 s przy 60). Rozszerzenia i długie wideo działają też w Ultra. Rozszerzenie zachowuje rozmiar klipu, który kontynuuje, i poniżej 720p jest rozliczane w cenie 720p.
• Czas: kilka minut dla klipu 5 s, dłużej dla klipu 20 s. Start może czekać na zwolnienie się dużej karty graficznej.
• Brak przejścia (end_image) w Ultra (ultra_incompatible).
• Brak klatek kluczowych (keyframes) w Ultra (keyframes_mode).
• LoRA postaci z twojego konta działa w Ultra tak samo jak w normalnym trybie.

Multi-Ref Wideo

Klip, w którym gra od 1 do 4 postaci (do 12 w Ultra), każda rozpoznawalna, w opcjonalnej lokacji, z zapisanymi obiektami, zwierzętami i zapisaną lokacją gdy ich potrzebujesz. Postacie pochodzą z GET /characters: stworzone z jednego zdjęcia przez API lub w aplikacji. Obiekty, zwierzęta i lokacje pochodzą z GET /subjects. Dodaj obiekt multiref do POST /videos (uprawnienie videos) i wywołuj każdą postać przez @Imię w prompcie:

{
  "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 po angielsku, jeden akapit w czasie teraźniejszym; Sound: dla dźwięku, linie dialogowe w cudzysłowie, exactly 2 people i pozycja każdej osoby gdy to pomaga, bez negacji. Stworzenie opisane przez to, czym jest. @Imię nieodpowiadające żadnej postaci jest odrzucane (unknown_mention).
• Formaty (width x height): pionowy 480 x 832, 720 x 1280, 1088 x 1920; poziomy 832 x 480, 1280 x 720, 1920 x 1088; kwadratowy 480 x 480, 720 x 720, 1088 x 1088. Brak 4K; 480p tylko w trybie Jakość.
• Tryby: Jakość (domyślny) lub Ultra (quality: "max"). Brak rozszerzenia i brak przejścia.
• Długość: automatyczna (duration_auto, domyślnie) lub stała przy duration_auto: false i length 121 (5 s), 241 (10 s) lub 481 (20 s) przy 24 fps; przy innym tempie te same czasy trwania liczone w klatkach, najwyżej 481 (przy 30: 145, 297, 481; przy 60: 297, 481).
• Liczba klatek: fps 24, 30 (domyślnie) lub 60, jak dla każdego klipu; length liczy klatki przy tym tempie, najwyżej 481 (16 s przy 30, 8 s przy 60).
• Cena: cena klipu. W trybie Jakość stała cena formatu z powyższego cennika, podwojona z dźwiękiem; 480p bez dźwięku pozostaje przy 5 kredytach (niska cena Jakości nie dotyczy Multi-Ref). POST /videos/quote z "multiref": true podaje dokładną cenę.
• Serwer dopasowuje ujęcia do dokładnego formatu wideo: wysyłaj postacie takimi, jakie są. Postać, która ma tylko jedno ujęcie jest renderowana, z warnings limited_likeness w odpowiedzi: podobieństwo jest ograniczone.
• Głosy z profilu: z dźwiękiem characters[0] i characters[1] mówią domyślnie głosem ze swojego profilu, gdy jest online (has_voice); voice generated pozwala modelowi stworzyć głos. Odpowiedź podaje głos każdej postaci w voices (character_id, voice: character, custom lub generated).
• Głosy postaci (voice_b64): model sprawia, że postać mówi tym głosem, z ruchem ust włącznie; serwer bierze jej pierwsze 5 sekund. Najwyżej dwa głosy, na characters[0] i characters[1] (silnik obsługuje 2 głosy). Porządkuj characters zgodnie z dialogiem: characters[0] mówi pierwszy, characters[1] odpowiada. Wymaga dźwięku ("audio": true), w przeciwnym razie voice_requires_audio; głos na innej postaci: voice_slot; nieczytelny plik: unsupported_audio_format; powyżej 4 MB: audio_too_large. Używane jest tylko pierwszych 5 sekund: wyślij krótki fragment. Całe ciało żądania musi mieć mniej niż 30 MB (powyżej tego odpowiedź 413 bez treści JSON). Brak dodatkowych opłat.
• Odpytywanie, pobieranie i anulowanie są takie same jak dla każdego wideo (patrz Odpytywanie, pobieranie, anulowanie, powyżej).

Zapisane obiekty, zwierzęta i lokacje. Dwa kolejne pola multiref obsadzają podmioty zapisane z twoich własnych obrazów:

name domyślnie przyjmuje pierwsze słowo nazwy podmiotu, a każde @Imię w prompcie jest dopasowywane jak imię postaci. Lokacja przekazana w subjects lub obiekt przekazany jako location jest odrzucany (invalid_subject_type). Cena się nie zmienia: to cena klipu. Obiekt jest używany z pierwszymi 5 obrazami (w Ultra ze wszystkimi, najwyżej 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."

W Ultra klip Multi-Ref podlega zasadom Ultra rozliczanego za sekundę: ta sama cena za sekundę, dźwięk w cenie, od 4 do 30 s przy 24 klatkach na sekundę (5 s przy długości automatycznej), od 480p do 1080p, bez ziarna.

• Każda postać idzie ze swoją character sheet (lub, bez niej, ze wszystkimi swoimi obrazami), a serwer składa całość w jeden obraz; każdy obiekt, zwierzę lub lokacja ze wszystkimi swoimi obrazami (najwyżej 6).
• Pierwszy render postaci przygotowuje ten obraz, co trwa kilkadziesiąt sekund dłużej: jego jobId zaczyna się wtedy od sdp- i śledzi się go jak pozostałe.
• Bez głosu: voice_b64 i głos z profilu są ignorowane (warnings voice_ignored), a strength nie ma wpływu.
• Silnik może odrzucić obraz referencyjny (na przykład prawdziwą twarz): render kończy się jako failed z powodem, a nic nie jest naliczane.

Style, stroje i ruch. Tylko w Ultra (quality: "max"), trzy dodatkowe pola multiref; w innym trybie żądanie jest odrzucane (multiref_ultra_only), nigdy nie jest renderowane bez nich.

• Najwyżej 30 obrazów w Ultra, łącznie postaci, obiekty, style, stroje i lokacja (multiref_too_many_images), w tym najwyżej 12 postaci (powyżej multiref_characters_required). Zalecane jest 8: od 9 do 12 renderowanie przechodzi z warnings many_characters, bo niektórych może brakować lub mogą się mieszać. Styl poza styles lub strój poza outfits jest odrzucany (invalid_subject_type).
• Cena ruchu: 3 kredytów za sekundę wideo ruchu (zaokrąglonego w górę do pełnej sekundy), oprócz renderu, podane w GET /pricing (ultra.motion_per_second); POST /videos/quote z tym samym multiref.motion zwraca motion_seconds i dokładną cenę.
• Bezpośrednie przesyłanie ciężkiego wideo ruchu: POST /motions z { "size": <bajty> } (najwyżej 20 MB) zwraca motion_id, upload_url, headers i expires_in (900 s); wyślij plik przez PUT upload_url dokładnie z tymi headers, a następnie przekaż multiref.motion.motion_id do POST /videos w ciągu 2 godzin. Jeden motion_id służy do jednego renderu.

"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."

Kody błędów stylów, strojów i ruchu są w Limity i błędy.

Dzięki serwerowi MCP agent robi to wszystko za pomocą tendre_multiref_video: opisz scenę i nazwij postacie, obiekty, zwierzęta i lokację (subjects, location_id).

Face swap

Osoba filmowana w twoim własnym wideo staje się jedną z twoich postaci: twarz, włosy, ciało i strój (albo tylko głowa, zob. part), zachowując jej gesty, ruch ust i scenografię, a także głos, chyba że postać ma własny (zob. voice). To Face swap z aplikacji, na jednym fragmencie do 20 s: jedna postać, bez łączenia i bez przejścia. Żądanie to POST /faceswap (uprawnienie 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
}

Wideo i głos razem: najwyżej 22 MB, żeby całe ciało żądania pozostało poniżej 30 MB (powyżej tego odpowiedź 413 bez treści JSON).

• Serwer przygotowuje wszystko. Wycina fragment, ustawia go na roboczą liczbę klatek (30 fps dla źródła przy 29 fps lub więcej, 50 i 60 włącznie, 24 poniżej) i na roboczy format (wielokrotności 128, krótszy bok 768, proporcje najbliższe twojemu wideo) oraz dopasowuje ujęcia postaci do tego formatu.
• Co otrzymujesz to wideo fragmentu w roboczym formacie, około jednego megapiksela (768 x 1408 dla pionowego wideo na przykład), z proporcjami twojego wideo w granicach 5%. Pełna rozdzielczość i kilka postaci po kolei pozostają domeną aplikacji desktopowej tendre.AI: nakłada ona postać z powrotem na oryginalne wideo w pełnej rozdzielczości i łączy kilka postaci.
• Cena: 6 kredytów za sekundę przygotowanego fragmentu (seconds w odpowiedzi), zaokrąglone w górę do następnego kredytu. Odpowiedź zawiera jobId, seed, cost i przygotowany fragment (width, height, length, fps, seconds, audio, voice, views, part). Postać, która ma tylko jedno ujęcie jest renderowana, z warnings limited_likeness.
• Brak wyceny: ani POST /videos/quote, ani tendre_quote z MCP nie obsługują Face swap. Żeby wyliczyć cenę przed przesłaniem, odczytaj grid.body_swap z GET /pricing: sekundy fragmentu x per_block_720p (cena bloku) / block_seconds (długość bloku), zaokrąglone w górę do następnego kredytu.
• Niektóre sceny są renderowane z trzech portretów postaci przyciętych do głowy (heads_only w odpowiedzi) i strój z jej ujęć nie jest już narzucany: decyduje scena.
• Face swap liczy się jako użycie postaci i przesuwa jej termin usunięcia, jak Multi-Ref.
• Odpytywanie, pobieranie i anulowanie są takie same jak dla każdego wideo (patrz Odpytywanie, pobieranie, anulowanie, powyżej): GET /videos/{jobId}, GET /videos/{jobId}/file, POST /videos/{jobId}/cancel.
• Własne błędy: 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 (głos powyżej 2 MB), face_swap_too_large (fragment nadal za ciężki po przygotowaniu: skróć duration), server_busy (dwa wideo są już przygotowywane: ponów po Retry-After, 20 s), face_swap_unavailable i face_swap_price_missing (Face swap zamknięty lub bez ceny: ponów później). Co oznacza każdy z nich: Limity i błędy.
• Twoje wideo przechodzi przez nasze serwery podczas przygotowania, a następnie trafia do karty graficznej, która je renderuje, jak każdy obraz źródłowy.

Używaj tylko wideo osób, które wyraziły zgodę: to zasada warunków użytkowania.

Dzięki serwerowi MCP agent robi to wszystko za pomocą tendre_face_swap.