Video Character Swap: referencje, wybór celu i przegląd

Korzystaj z Character Swap, gdy podmiana ma zmienić cały wygląd osoby, w tym sylwetkę i ubiór, a scena, ruch kamery i oryginalny dźwięk mają zostać zachowane. Character Swap pozwala wskazać, która osoba w klipie zostanie podmieniona: przeanalizuj klip końcowy, obejrzyj ponumerowane podglądy, a następnie wyślij wybrany indeks podglądu razem z jednym do trzech obrazów osoby zastępczej. Jeśli oryginalny ubiór ma zostać zachowany, użyj zamiast tego przepływu head swap lub face swap.

W SpicyAPI analiza i edycja to osobne płatne zadania. Siedmiosekundowe źródło kosztuje łącznie 0,72 $ w 480p lub 1,28 $ w 720p: jedna analiza plus edycja zaokrąglana w górę do dziesięciu sekund. Playground wykonuje oba kroki w przeglądarce, a API przyjmuje te same dane wejściowe. Potrzebujesz zgody zarówno na materiał, jak i na podobieństwo wskazane na obrazach referencyjnych.

Przygotuj scenę trwającą siedem sekund i podmianę całej postaci

Nasz przykład to siedmiosekundowe ujęcie, w którym ktoś niesie zamkniętą skrzynkę narzędziową do stołu, a obok stoi inna osoba dorosła. Osoba niosąca jest zastępowana wymyśloną dorosłą kobietą w granatowej kurtce roboczej i spodniach w kolorze grafitowym, czyli tak, jak w ilustracjach poniżej. Stół, skrzynka narzędziowa, druga osoba i oryginalny występ pozostają bez zmian.

Wyeksportuj dokładnie to siedmiosekundowe źródło, które zamierzasz edytować. Zachowaj początkowy chwyt, czynność przenoszenia i puszczenie, gdy skrzynka dociera do stołu. Dane wejściowe to MP4 długości 5–30 s o maksymalnym rozmiarze 90 MB. Przesłanie pliku jest najpewniejszą drogą; bezpośredni odnośnik musi prowadzić do samego pliku MP4, ponieważ strona z odtwarzaczem nie zadziała (opłata zostanie zwrócona). Przycięcie lub ponowne zakodowanie po analizie wymaga nowej analizy.

Tracker śledzi osoby, które pozostają dostatecznie duże i widoczne, więc wytnij odcinek, który ma znaczenie, i unikaj długich okresów, w których wybrana osoba jest całkowicie zakryta. Krótszy fragment kosztuje też mniej, bo edycja jest rozliczana w blokach po pięć sekund.

Na podmianę przygotuj frontalne ujęcie całej postaci i ujęcie z trzech czwartych tej samej dorosłej osoby, w tym samym ubiorze. Jedna wyraźna referencja jest akceptowana; trzy to maksimum na jeden cel. Portret głowy i ramion zostawia sylwetkę oraz ubiór do zgadywania, więc pokaż rękawy, dłonie i obuwie oraz oświetl referencje tak jak materiał, zamiast wybierać najostrzejszy portret. Nie łącz twarzy jednej osoby, spodni innej i jeszcze innej kurtki na trzecim obrazie. Usługa otrzymuje je jako referencje do jednej podmiany, a nie jako osobno przypisane warstwy odzieży.

Przydatny brief do wygenerowania obrazu:

Referencyjny portret całej postaci wymyślonej dorosłej kobiety, około 30 lat, w prostej granatowej kurtce roboczej, spodniach w kolorze grafitowym i ciemnych płaskich butach. Swobodna poza przodem do kamery, widoczne dłonie, czytelne rękawy i obuwie, neutralne tło. Bez skrzynki narzędziowej, bez innych osób, bez napisów.

W razie potrzeby wygeneruj lub sfotografuj drugi kąt tego samego ustalonego projektu. Edycja character swap nie ma pola na prompt tekstowy, wyboru ubioru ani maski ciała, więc zamierzony ubiór musi znajdować się na obrazach referencyjnych.

Ilustracja zestawu referencji całej postaci od przodu i z trzech czwartych.

Najpierw wypróbuj w Playgroundzie

1. Otwórz stronę modelu Video Character Swap i zostań w zakładce Playground w widoku Form. Zaloguj się kontem z dodatnim saldem, aby uruchomić.
2. W Step 1, Find the people in your clip dodaj siedmiosekundowy plik MP4 w polu Input video (przesłanie jest pewniejsze niż odnośnik) i wybierz Resolution, której chcesz dla gotowego klipu: 480p lub 720p. Edycja musi użyć tej samej wartości.
3. Naciśnij Find people in this clip (0,08 $). Wszystkie wykryte osoby pojawią się w Step 2, Choose who to replace, po jednym przyciętym podglądzie na osobę.
4. Wybierz podgląd osoby niosącej skrzynkę narzędziową, dodaj od jednego do trzech obrazów referencyjnych osoby zastępczej i uruchom edycję. Seed jest opcjonalny.

Pozycja 0 to pierwszy zwrócony podgląd, a niekoniecznie osoba najbardziej z lewej lub największa, ponieważ kolejność wynika ze śledzenia, a nie z położenia na ekranie. Jeśli osoba niosąca to drugi podgląd, jest to indeks 1. Zachowuj zwróconą kolejność podczas zapisywania podglądów: alfabetyczne nazwy plików lub posortowana galeria mogą po cichu zmienić indeks.

Jeśli wybrana osoba nie ma podglądu, nie płać za edycję, zgadując sąsiedni numer. Żaden obraz referencyjny nie przywróci osoby bez podglądu, więc użyj ujęcia, w którym ta osoba jest wyraźnie widoczna. Analiza, która nikogo nie znajdzie, kończy się niepowodzeniem, a jej rezerwacja jest zwalniana; udana analiza jest pobierana nawet wtedy, gdy zdecydujesz się nie podmieniać.

Potem wywołaj to z kodu

Zainstaluj Python SDK (pip install spicyapi), ustaw SPICY_API_KEY i uruchom poniższy kod. Wysyła klip i dwie referencje, uruchamia analizę, wypisuje linki do podglądów, pyta, który indeks podmienić, a następnie wysyła edycję. Oba zadania są płatne.

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
RESOLUTION = "720p"     # must be identical in both calls

clip = client.upload_file("./workshop-seven-seconds.mp4")
front = client.upload_file("./replacement-front.png")
angled = client.upload_file("./replacement-three-quarter.png")

analysis_task = client.create_task(
    model="spicyapi/character-swap-v1/video-analyze",
    input_data={"video_url": clip["uri"], "resolution": RESOLUTION},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume analysis:", analysis_task["taskId"], flush=True)
analysis = client.wait_for_terminal(analysis_task["taskId"])
if analysis["state"] != "succeeded":
    raise RuntimeError(f"Analysis {analysis_task['taskId']} ended as {analysis['state']}")

previews = output_assets(analysis)
if not previews or any(p.get("pending") or p.get("unavailable") or not p.get("url") for p in previews):
    raise RuntimeError(f"Analysis {analysis_task['taskId']} has no ready previews; retrieve it before editing")
for index, preview in enumerate(previews):  # keep the returned order
    print(index, preview["url"])
chosen = int(input("Index of the person to replace: "))
if not 0 <= chosen < len(previews):
    raise ValueError("Choose one of the returned preview indices before creating an edit")

edit_task = client.create_task(
    model="spicyapi/character-swap-v1/video-edit",
    input_data={
        "analysis_task_id": analysis["taskId"],  # video_url is inherited from the analysis
        "resolution": RESOLUTION,
        "swap_targets": [{"object_index": chosen,
                          "image_urls": [front["uri"], angled["uri"]]}],
        "seed": 42,
    },
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume edit:", edit_task["taskId"], flush=True)
edit = client.wait_for_terminal(edit_task["taskId"])
if edit["state"] != "succeeded":
    raise RuntimeError(f"Edit {edit_task['taskId']} ended as {edit['state']}")
assets = output_assets(edit)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {edit_task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy it to your own storage now

Przesyłanie, oczekiwanie, błędy i ponowienia opisuje przewodnik subject swap, dokumentacja zadań oraz referencja Python SDK. Użyj tego samego klucza API w obu krokach i uruchom edycję w ciągu 24 godzin od analizy (przesłany klip też wygasa po dniu); jedna analiza może obsłużyć kilka osobno rozliczanych edycji. Osoby, których nie wymienisz, pozostają nietknięte, a indeks należy do tej analizy, więc nie używaj go ponownie jako ID postaci w innym ujęciu.

Podmiana całej postaci ma zachować scenę, ruch kamery, choreografię i oryginalny dźwięk. Taki zakres nie obiecuje niezmienionych pikseli tła ani nowego głosu.

Albo niech wykona to agent

Jeśli podmianę ma wykonać asystent, daj mu CLI albo serwer MCP. Oba pokazują cenę i proszą o potwierdzenie przed płatnym wywołaniem. Skill dodaje instrukcje do jednego lub drugiego.

• CLI. spicyapi wykonuje zadanie z terminala (npx @spicyapi/cli działa bez instalacji):

``bash spicyapi files upload ./workshop-seven-seconds.mp4 # prints a spicy:// URI spicyapi tasks create --model spicyapi/character-swap-v1/video-analyze \ --input-file analysis.json --idempotency-key workshop-analysis-v1 --wait ``

analysis.json zawiera {"video_url": "spicy://...", "resolution": "720p"}. Obejrzyj podglądy, a potem uruchom polecenie z video-edit, własnym kluczem workshop-edit-v1 oraz plikiem input.json zawierającym analysis_task_id, resolution i swap_targets. Klucz używaj ponownie tylko dla niezmienionego żądania; nowe źródło, nowy cel lub nowy zestaw referencji wymaga nowego klucza.

• Serwer MCP. Dodaj serwer MCP (jego fragment konfiguracji jest na tej stronie) do swojego asystenta, a potem zapytaj: "Przeanalizuj ./workshop-seven-seconds.mp4 w 720p za pomocą Character Swap i pokaż podglądy." Po wybraniu osoby powiedz: "Podmień indeks 1, używając ./replacement-front.png i ./replacement-three-quarter.png." Wywołuje spicyapi_upload_file, potem spicyapi_task_create (który zatrzymuje się na potwierdzenie ceny), potem spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instaluje Agent Skill, który uczy asystenta programistycznego odczytywać aktualny schemat i używać ponownie kluczy idempotencji. Sam nie uruchomi zadań, więc używaj go z CLI lub MCP. To, którego podglądu podmienić, pozostaje twoją decyzją.

Zrozum opłatę, zanim zrobisz warianty

Ceny pochodzą z publicznego katalogu (październik 2026).

Czas trwania edycji jest zaokrąglany w górę do pełnych bloków po pięć sekund, z minimum pięciu sekund i maksimum trzydziestu sekund. Źródło o długości 5 s zajmuje jeden blok; 5,1 s zajmuje dwa. Przed wysłaniem szacunek edycji rezerwuje maksimum trzydziestu sekund, 1,92 $ w 480p lub 3,60 $ w 720p, a różnica wraca po rozliczeniu zadania. Kontrola budżetu musi więc uwzględniać rezerwację, a nie tylko oczekiwaną kwotę końcową. Żądanie odrzucone przy tworzeniu (niezgodna rozdzielczość, błędny ID analizy, powtórzony indeks) niczego nie tworzy i nie pobiera.

Dwie edycje w 720p siedmiosekundowego źródła przy ponownym użyciu jednej analizy kosztują łącznie 2,48 $: 0,08 $ plus dwa razy 1,20 $. Zmiana referencji lub seeda to nowa płatna edycja, a nie bezpłatna poprawka.

Napraw właściwy problem

Ilustracja przeglądania wydrukowanej klatki.

Oglądaj osobę niosącą, skrzynkę narzędziową i niewybraną osobę dorosłą razem, w normalnej prędkości. Potem sprawdź chwyt, kontakt ze stołem i puszczenie. Nowa twarz może wyglądać świetnie, kiedy centralna akcja się nie udaje. Jeśli wada dotyczy tylko ostatniego pół sekundy, może wystarczyć przycięcie; jeśli chwyt jest zepsuty przez całe ujęcie, wybierz jaśniejsze źródło albo zastosuj węższy zakres podmiany głowy, gdy można zostawić oryginalne ciało i ubiór.

Skopiuj zaakceptowany klip do własnej pamięci, zanim wygaśnie: wyniki są przechowywane około 14 dni (zob. przechowywanie i dostarczanie mediów).