API Video Head Swap: analiza, wybór celu i edycja

Video Head Swap to dwuetapowy przepływ API: przeanalizuj plik MP4 trwający od 5 do 30 sekund, obejrzyj numerowane podglądy głów, a następnie przekaż wybraną pozycję i portrety zastępcze do edycji. Twarz, fryzura, kolor włosów i kształt głowy się zmieniają; ciało, ubiór, ruch, dźwięk i wszyscy, których nie wybierzesz, zostają tak, jak nakręcono.

Tutaj najpierw widzisz każdą wykrytą głowę i wskazujesz tę, której chcesz, zanim zapłacisz za edycję. Edycja operuje na istniejącym wideo; nie ożywia dwóch zdjęć w występ (do tego użyj modelu obraz na wideo).

Wybierz właściwą podmianę

Podmiana twarzy jest tańsza i prostsza, gdy włosy z materiału mogą zostać. Podmiana głowy opłaca się, gdy nowe włosy są częścią postaci, a kosztem jest widoczne na szyi połączenie, które musisz sprawdzić.

Przygotuj źródło i portrety referencyjne

Korzystaj wyłącznie z wizerunków, które masz prawo przetwarzać: własnego, wykonawcy z podpisaną zgodą albo wygenerowanej głowy. Wszystkie widoczne osoby muszą być dorosłe. Oba wywołania są bez cenzury, więc SpicyAPI nie dodaje filtra treści i to ty odpowiadasz za tę kontrolę.

W tym przykładzie fikcyjny dorosły w kurtce w kolorze rdzy odwraca się do innego dorosłego podczas dwunastosekundowej rozmowy. Podmień tylko głowę pierwszej osoby; drugą osobę, ubiór i dialog pozostaw bez zmian.

Wyeksportuj ostateczne źródło przed analizą: MP4, do 90 MB, od 5 do 30 sekund. video_url przyjmuje publiczny link HTTPS zwracający sam plik MP4, a nie stronę odtwarzacza HTML, albo identyfikator spicy:// z darmowego schematu wgrywania, który jest najpewniejszą drogą dla pliku lokalnego. Jeśli później przytniesz, wykadrujesz lub przekodujesz źródło, uruchom analizę ponownie.

Przygotuj od 1 do 3 portretów tej samej dorosłej osoby zastępczej. Widok z przodu i widok trzech czwartych to dobry punkt wyjścia; dodaj profil, jeśli źródło zawiera wyraźny obrót głowy. Utrzymaj fryzurę i pozorny wiek spójne w całym zestawie. Dopasuj je też do materiału: oświetl portrety od strony, z której oświetlone jest ujęcie, a głowę ustaw w zbliżonym kącie. Połączenie na szyi jest miejscem, w którym widać niedopasowanie, a żadne pole żądania tego nie kompensuje. Referencje ubioru w całej postaci należą do podmiany postaci; to zadanie wymaga wyraźnie widocznej głowy i włosów.

Do fikcyjnego obrazu referencyjnego użyj briefu w stylu:

Referencyjny portret fotograficzny jednego fikcyjnego dorosłego mężczyzny, około 35 lat, z krótkimi ciemnymi włosami, zadbaną brodą i neutralnym wyrazem twarzy, w gładkiej, w pełni zapiętej koszuli. Miękkie, równomierne światło, twarz i włosy bez przeszkód, proste tło. Widok z przodu, bez innych osób, bez tekstu.

Pozostałe ujęcia twórz na podstawie zatwierdzonej tożsamości, zamiast niezależnie prosić o niepowiązane osoby. Edycja nie ma pola prompt, więc cały wynik niosą referencje.

Ilustracja zestawu referencji: widok z przodu, w trzech czwartych i z profilu.

Najpierw sprawdź to w Playground

1. Otwórz stronę edycji Video Head Swap i zostań w zakładce Playground, w widoku Form. Zaloguj się kontem z saldem, aby uruchomić.
2. Krok 1, Find the people in your clip. Dodaj klip w polu Input video (upuść plik MP4 lub użyj Asset URL) i wybierz Resolution, 480p albo 720p. Edycja musi użyć tej samej wartości, więc wybierz tę, którą ma mieć gotowy klip. Naciśnij Find people in this clip (0,08 $).
3. Krok 2, Choose who to replace. Każda wykryta głowa pojawia się jako numerowany podgląd. Wybierz tę, której chcesz, i dodaj od jednego do trzech zdjęć referencyjnych dorosłej osoby zastępczej. Ustaw Seed tylko wtedy, gdy chcesz sprawiedliwie porównać zestawy referencji; w przeciwnym razie pomiń go.
4. Uruchom edycję, a następnie sprawdź w wyniku szczękę, szyję, włosy i kołnierz, z włączonym dźwiękiem.

Analiza pozostaje dostępna do ponownego użycia przez 24 godziny, więc możesz wypróbować inny zestaw referencji na podstawie tych samych podglądów, nie płacąc ponownie za śledzenie. Każda zaakceptowana edycja, także z nowym zestawem referencji lub nowym seedem, to nowe płatne zadanie. Jeśli żaden podgląd nie pokazuje wybranej osoby, rozwiązaniem jest wyraźniejsze ujęcie: głowy, której nigdy nie widać wyraźnie, nie da się śledzić, a klip bez możliwej do śledzenia głowy kończy się błędem, a zarezerwowane środki zostają zwolnione.

Strona analizy wykonuje krok 1 samodzielnie; udana analiza jest płatna nawet wtedy, gdy się na tym zatrzymasz.

Potem uruchom to z kodu

Zainstaluj Python SDK (pip install spicyapi), ustaw SPICY_API_KEY w swoim środowisku i zapisz to jako swap.py. analyze wypisuje adresy URL podglądów; edit przyjmuje identyfikator zadania analizy i wybraną przez ciebie pozycję podglądu. Edycja musi użyć tego samego klucza API i tej samej rozdzielczości co analiza, a video_url nie przyjmuje: dziedziczy przeanalizowany klip.

import sys
import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

def run(model: str, input_data: dict) -> tuple[str, list]:
    task = client.create_task(model=model, input_data=input_data,
                              idempotency_key=str(uuid.uuid4()))
    final = client.wait_for_terminal(task["taskId"])
    if final["state"] != "succeeded":
        raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
    return task["taskId"], output_assets(final)

if sys.argv[1] == "analyze":
    task_id, previews = run("spicyapi/head-swap-video-v1/video-analyze", {
        "video_url": "https://your-media.example/conversation.mp4",
        "resolution": "720p",
    })
    print("analysis task:", task_id)
    for position, asset in enumerate(previews):   # position 0 is the first image returned
        print(position, asset["url"])
else:  # python swap.py edit <analysis_task_id> <position>
    _, outputs = run("spicyapi/head-swap-video-v1/video-edit", {
        "analysis_task_id": sys.argv[2],
        "resolution": "720p",
        "swap_targets": [{
            "object_index": int(sys.argv[3]),
            "image_urls": [
                "https://your-media.example/replacement-front.png",
                "https://your-media.example/replacement-three-quarter.png",
            ],
        }],
        "seed": 42,
    })
    print(outputs[0]["url"])  # copy the video to your own storage now

Uruchom python swap.py analyze, otwórz każdy podgląd i zapisz numer wybranej osoby dorosłej (pozycja 0 to pierwszy zwrócony obraz, a nie reguła od lewej do prawej; nigdy nie wracaj do 0, jeśli twojej osoby tam nie ma), potem python swap.py edit <analysis_task_id> 1. Edycja przyjmuje od 1 do 10 celów, każdy z od 1 do 3 obrazów referencyjnych tej samej osoby; nie ma pól maski, ubioru, dźwięku ani promptu. Tworzenie, oczekiwanie, ponowne próby, klucze idempotencji i pobieranie są opisane w przewodniku po zadaniach oraz w dokumentacji Python SDK; plik lokalny przechodzi przez darmowy schemat wgrywania i wraca jako identyfikator spicy:// dla video_url.

Albo niech wykona to agent

Gdy oba wywołania ma wykonać asystent, wszystkie trzy oficjalne narzędzia pokazują cenę i pytają o zgodę przed płatnym wywołaniem.

• CLI. Umieść obiekt input analizy (video_url, resolution) w pliku analysis.json, a następnie:

``bash spicyapi tasks create --model spicyapi/head-swap-video-v1/video-analyze --input-file analysis.json --wait ``

Edycję uruchom w ten sam sposób z plikiem edit.json. Zobacz dokumentację CLI; npx @spicyapi/cli działa bez instalowania.

• Serwer MCP. Dodaj serwer MCP, a następnie zapytaj: "Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." Wgrywa plik przez spicyapi_upload_file, wywołuje spicyapi_task_create, które zatrzymuje się w celu potwierdzenia ceny, a potem spicyapi_task_wait. Sam wybierz pozycję, a następnie poproś o edycję.
• Skill. npx skills add spicyapi-ai/spicy-skill instaluje Agent Skill, dzięki któremu asystent programistyczny czyta bieżący schemat modelu zamiast zgadywać nazwy pól.

Jak wygląda gotowa edycja

Opublikowany poniżej przykład modelu to dziesięciosekundowy klip źródłowy i jego edycja w 480p z jednym portretem referencyjnym. Włosy i twarz się zmieniają; sukienka, chód, światło z tyłu i kamera zostają. Najpierw sprawdź szczękę i linię szyi, tam gdzie widać niedopasowanie światła lub kąta.

Ile to kosztuje

Edycja kosztuje 0,064 $ za rozliczoną sekundę w 480p i 0,12 $ w 720p. Rozliczenie działa blokami po pięć sekund, z minimum pięciu sekund i maksimum trzydziestu sekund. Klip długości 10 sekund w 480p kosztuje łącznie 0,72 $: 0,08 $ za analizę plus 0,64 $ za edycję.

Przed rozliczeniem edycja rezerwuje maksimum trzydziestu sekund, 1,92 $ w 480p lub 3,60 $ w 720p. Klip długości dwunastu sekund w 720p jest zarezerwowany na 3,60 $, mimo że opłata za edycję wynosi 1,80 $; reszta jest zwalniana, gdy zadanie zostanie rozliczone.

Diagnozuj wybór, tożsamość i dostarczenie osobno

Ilustracja przeglądu włosów, kołnierza i ręki na pierwszym planie.

Odtwórz zwrócony materiał z dźwiękiem. Edycja zachowuje dźwięk i ruch ciała ze źródła; nie zmienia głosu mówiącej osoby, a scena nie jest gwarantowana identyczna piksel w piksel. Sprawdź także osobę niewybraną, zwłaszcza przy przejściach. Jeśli dłoń przecina wymienioną twarz, przejrzyj klatka po klatce moment kontaktu i ponownego pojawienia się, zamiast zatwierdzać wyłącznie atrakcyjną pierwszą klatkę.

Od razu zapisz zaakceptowany materiał we własnym magazynie: odnośniki do wyniku działają około 20 minut, a wyniki są przechowywane najwyżej 14 dni, więc identyfikator analizy, obraz podglądu i tymczasowy adres mediów nie są trwałą kopią.