Przepływ pracy API wymiany twarzy z AI: autoryzowane przesłanie, zadania asynchroniczne i pewne dostarczenie

Porównanie zdjęć referencyjnych i koloru przed wymianą.

Face Swap w SpicyAPI to rodzina endpointów bez cenzury, które przyjmują dwa obrazy (albo jeden obraz i klip), bez promptu i bez maski. Ten przewodnik omawia, który endpoint wywołać, jak najpierw sprawdzić go w Playground, a potem z kodu lub przez agenta, co sprawdzić w wyniku oraz jak zachować rezultat po tym, jak platforma go usunie.

Wybierz endpoint do zadania

Zacznij od Face Swap za 0,013 $. Przejdź na Pro, gdy wymieniona twarz wygląda gładsza albo ostrzejsza niż reszta kadru, a na Plus, gdy oba zdjęcia mają wyraźnie różne odcienie skóry albo barwy światła. 200 wariantów awatara kosztuje 2,60 $ w Face Swap i 32 $ w Pro, więc sprawdź najtrudniejszą parę w obu. Plus ma pole prompt, które nic nie robi, więc pomiń je, a okulary lub wyraz twarzy wstaw do zdjęcia docelowego.

Video Face Swap rozlicza klip źródłowy w pełnych blokach 10-sekundowych, więc 12-sekundowy klip jest pobierany jak 20 sekund (0,52 $), a 40-sekundowy jak 1,04 $. Przy wysłaniu zatrzymywane jest oszacowanie dla 40 sekund (1,04 $), a różnica jest zwalniana po rozliczeniu zadania. Przytnij do granicy bloku przed wysłaniem.

Co endpointy robią z prawdziwymi twarzami

Te endpointy są wymienione jako bez cenzury: SpicyAPI nie dodaje skanu twarzy na żądanie ani weryfikacji osoby realnej. Niepowodzenia zwykle wynikają z wejścia (brak wykrywalnej twarzy, nieosiągalny plik), choć pojedynczy model może mimo to odmówić żądania. Polityka dopuszczalnego użytkowania zabrania podszywania się, intymnego lub seksualizowanego wykorzystania podobieństwa osoby realnej bez jej zgody oraz wszystkiego, co dotyczy nieletnich; po zgłoszeniu SpicyAPI może usunąć zapisane zasoby i wstrzymać dostęp. Zdjęcie publiczne ani wcześniejsza relacja nie są zgodą. Rejestr zgody należy do ciebie i powinien być przed przyciskiem przesyłania:

• Zalogowany użytkownik potwierdza, że ma zgodę osoby przedstawionej na obu zdjęciach i na to konkretne użycie; zapisz to potwierdzenie razem z projektem (kto, jaki zasób, jakie użycie, kiedy).
• Żadnych zdjęć nieletnich i żadnego użycia, które podszywa się pod osobę realną, by kogoś oszukać.

Przechowuj to jako zapisy produktowe, a nie w promptach, zdarzeniach analitycznych ani logach.

Przygotuj wejście, które nie zawiedzie

Nie ma ustawienia siły do dostrajania, więc zły wynik oznacza inną parę wejściową.

• Twarze frontalne, duże i ostre. Mocne kąty boczne, rozmycie ruchem, gęste przesłonięcia (ręce, maski, duże okulary) i bardzo małe twarze pogarszają przenoszenie albo powodują niepowodzenie żądania. Duża, ostra, frontalna twarz referencyjna daje najlepszy wynik.
• Ten sam kierunek światła. Wymiana nie zmienia oświetlenia celu, więc referencja oświetlona z drugiej strony jest widoczna jako szew na linii żuchwy. Dopasuj kierunek i przybliżony odcień skóry albo wybierz inną referencję. Plus wyrównuje tylko odcień skóry; nie naprawia rozbieżności kierunku światła.
• Jedna twarz na obrazie. Przy zdjęciach grupowych Face Swap i Video Face Swap przyjmują face_mapping: maksymalnie 10 wpisów, każdy łączy twarz referencyjną z twarzą docelową, numerowanych od 0 w kolejności wykrywania. Po każdej zmianie obrazu sprawdź numerację ponownie. Plus i Pro zakładają jedną twarz; najpierw przytnij.

``json "face_mapping": [{ "reference_face_index": 0, "target_face_index": 1 }] ``

To wymienia referencyjną twarz 0 na drugą twarz znalezioną w celu. Pomiń to pole, aby wymienić pojedynczą twarz.

• Bezpośrednie linki do plików. Adresy obrazów muszą prowadzić do pliku bez logowania. W przypadku wideo strona odtwarzająca klip zwraca HTML, nie klip, a wywołanie kończy się błędem ze zwrotem opłaty; wgraj plik.
• Role nie są zamienne. image_url to obraz, który jest zmieniany; reference_image_url dostarcza twarz. Zamiana obu jest prawidłowym żądaniem o innym wyniku i nie zwraca błędu, więc wymiana w złą stronę wygląda jak błąd modelu.

Limity dla wideo: MP4 do 90 MB i od 3 do 40 sekund, obraz referencyjny JPG, PNG lub WEBP do 10 MB. Utrzymaj twarz dużą w kadrze i nie odwracaj jej na długo. Endpoint działa najlepiej z jedną osobą w kadrze; w przypadku klipu z kilkoma osobami dodaj face_mapping (ten sam kształt co wyżej, numerowany w kolejności wykrywania) albo przytnij do właściwej osoby.

Najpierw sprawdź w Playground

Otwórz stronę zadania Face Swap i użyj zakładki Playground (konfiguruj, oszacuj, uruchom). Wpisz obraz docelowy i obraz twarzy referencyjnej, sprawdź szacunek ceny dla swoich ustawień i uruchom. Najtrudniejszą parę sprawdź tutaj, zanim napiszesz kod: jeśli wynik w Playground jest zły, będzie zły także przez API, a naprawą jest inna para wejściowa. Head Swap ma tę samą zakładkę do wymiany całej głowy.

Potem wywołaj z kodu

Zainstaluj Python SDK (pip install spicyapi), ustaw SPICY_API_KEY w środowisku i uruchom:

import json
import uuid
from pathlib import Path
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
job_file = Path("avatar-8841-layout-02-v1.json")  # keep this file to resume this job

if job_file.exists():
    job = json.loads(job_file.read_text())
else:
    target = client.upload_file("./layout-02.png")
    face = client.upload_file("./approved-portrait.png")
    job = {
        "key": str(uuid.uuid4()),
        "input": {"image_url": target["uri"], "reference_image_url": face["uri"],
                  "style": "realistic", "seed": 4242},
    }
    job_file.write_text(json.dumps(job))  # persist the exact key and payload BEFORE submit

if "taskId" not in job:
    task = client.create_task(
        model="spicyapi/face-swap-v1/edit", input_data=job["input"],
        idempotency_key=job["key"],
    )
    job["taskId"] = task["taskId"]
    job_file.write_text(json.dumps(job))

print("Resume task:", job["taskId"], flush=True)
final = client.wait_for_terminal(job["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {job['taskId']} ended as {final['state']}")
assets = output_assets(final)
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 {job['taskId']} has no ready output; check this task, not a new run")
print(assets[0]["url"])  # copy it to your own storage now

Uruchom jeden proces na plik zadania. Jeśli oczekiwanie przekroczy limit czasu, uruchom ponownie z tym samym plikiem, aby wznowić zapisane zadanie. Jeśli samo wysłanie przekroczyło limit czasu, zanim zwróciło identyfikator, zachowaj plik i porównaj to żądanie przed ponowną próbą; ochrona idempotencji nie jest trwała. Nowej nazwy pliku zadania używaj tylko wtedy, gdy chcesz nowego płatnego żądania.

Przesyłanie, oczekiwanie, błędy i ponowne próby opisuje przewodnik Subject Swap oraz referencja Python SDK. Video Face Swap używa spicyapi/face-swap-video-v1/video-edit z video_url i reference_image_url.

Albo niech zadanie wykona agent

Jeśli asystent ma wykonać wymianę za ciebie, daj mu CLI albo serwer MCP. Oba pokazują cenę i proszą o potwierdzenie przed płatnym wywołaniem. Skill dokłada instrukcje do obu.

• CLI. spicyapi uruchamia jedno zadanie z terminala lub skryptu (npx @spicyapi/cli działa bez instalacji):

``bash spicyapi files upload ./layout-02.png # prints a spicy:// URI SWAP_REQUEST_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')" printf 'Save this request key: %s\n' "$SWAP_REQUEST_KEY" spicyapi tasks create --model spicyapi/face-swap-v1/edit \ --input-file input.json --idempotency-key "$SWAP_REQUEST_KEY" --wait ``

input.json zawiera ten sam obiekt input co wyżej, z identyfikatorami spicy://. Ten blok rozpoczyna nowe zadanie. Zachowaj wypisany klucz i identyfikator zadania; po przekroczeniu limitu czasu wznów tamto zadanie zamiast ponownie uruchamiać blok z nowym kluczem.

• Serwer MCP. Dodaj serwer MCP do asystenta, a potem zapytaj: "Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap." Wywołuje spicyapi_upload_file, potem spicyapi_task_create (który zatrzymuje się na potwierdzenie ceny), potem spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill instaluje Agent Skill, który uczy asystenta programistycznego czytania bieżącego schematu, ponownego używania kluczy idempotencji i zapisywania wyników zamiast zgadywania. Sam nie uruchomi zadań, więc użyj go razem z CLI lub MCP.

Rejestr zgody i kopiowanie wyników do własnej pamięci dotyczą wywołań agenta dokładnie tak samo jak twoich.

Sprawdź, zanim uznasz to za zrobione

succeeded oznacza, że generowanie się zakończyło. Przed pobraniem sprawdź, czy zasób ma użyteczny URL i czy żadne z pól pending i unavailable nie ma wartości true; dopóki pending ma wartość true albo URL brakuje, odpytuj to samo zadanie. Gotowość do dostarczenia nie oznacza jednak, że obraz został zatwierdzony. Przy wideo sprawdź cięcia i szybki ruch, nie tylko pierwszą klatkę. Wynik podobieństwa jest sygnałem diagnostycznym, nie zgodą ani zatwierdzeniem publikacji.

Dwa sprawdzenia, które zmieniają to, co zrobisz dalej:

• Włosy są częścią projektu (postać z gry, maskotka). Face Swap zachowuje fryzurę celu, więc nowa twarz ląduje pod starymi włosami. Użyj zamiast tego Head Swap z nieruchomym obrazem karty postaci jako referencją i porównuj każde wyjście z kartą: dryfująca twarz na stabilnej kompozycji to problem tożsamości, odwrotność to problem kadrowania, a ponowienie naprawia tylko jeden z nich.
• Jeden portret w kilku layoutach. Uruchom Face Swap raz na layout z tą samą referencją i tym samym seed. Przyjmij wynik, gdy twarz jest rozpoznawalna względem portretu w kadrowaniu, który opublikujesz, gdy okulary i linia włosów nie dryfują i gdy nie pojawiają się dodatkowe osoby; zachowaj wraz z nim rewizję referencji, rewizję celu i identyfikator zadania.

Dostarcz: skopiuj wynik sam

Przesłane źródła są usuwane po jednym dniu, a wyniki najpóźniej po 14 dniach (retention.outputsExpireAt zawiera dokładny czas). Pobierz wynik i przechowuj go sam; link do wyniku działa około 20 minut. Zobacz przewodnik retencji.

Gdy pójdzie nie tak

FAQ

Czy API odmówi obsługi twarzy prawdziwej osoby?

SpicyAPI nie sprawdza: nie ma weryfikacji osoby realnej ani skanu na żądanie, a niepowodzenia zwykle wynikają z wejścia. Pojedynczy model może mimo to odmówić, a polityka dopuszczalnego użytkowania zabrania podszywania się, intymnego użycia bez zgody i nieletnich. Rejestr uprawnień zbuduj sam.

Czy mogę wysłać wideo i obraz w jednym wywołaniu?

Tak, w Video Face Swap: jeden MP4 i jedno zdjęcie referencyjne. Dla kilku osób w jednym klipie użyj tam face_mapping albo dwuetapowy przepływ Video Head Swap, gdy potrzebujesz całych głów.

API hostowane czy samodzielnie hostowana wymiana open source?

Endpoint hostowany kosztuje 0,013 $ za obraz i zdejmuje z ciebie udostępnianie GPU i utrzymanie modelu. Samodzielne hostowanie zastępuje opłaty za obraz kosztami GPU i operacyjnymi; czy jest tańsze, zależy od przepustowości i wykorzystania. Wysoki, stały wolumen rozłoży te koszty na więcej obrazów, ale nadal musisz utrzymywać kontrolę zgody i retencji.

Czy to jest to samo co ogólne API do edycji obrazów?

Nie. Endpoint wymiany przyjmuje dwa obrazy (albo jeden obraz i klip), bez promptu i bez maski, a każdy endpoint decyduje, co zostaje z celu: Face Swap zachowuje włosy, Head Swap je zastępuje. Ta sama para wejściowa może przejść przegląd inaczej w każdym z nich, więc najpierw wybierz endpoint.

Czy powinienem zachować oryginalne portrety razem z wynikiem?

Tylko jeśli masz wyraźny powód i ujawnioną politykę retencji. Przesłane źródła w SpicyAPI i tak są usuwane po dniu, więc zachowaj identyfikatory rewizji referencji i celu oraz identyfikator zadania jako ślad pochodzenia, zamiast trwałej kopii każdego portretu.

Czy potrzebuję webhooków, czy wystarczy odpytywanie?

Samo odpytywanie działa i jest ścieżką odzyskiwania: odczytuj co kilka sekund albo dodaj wait (do 60 s) przy tworzeniu krótkich wymian obrazu. Dodaj webhook, aby obniżyć opóźnienie, zapisuj każde zdarzenie tylko raz i traktuj odpytywanie jako uzgadnianie pominiętych wywołań zwrotnych.

Co powinieneś umieć odpowiedzieć

Funkcja wymiany twarzy zyskuje zaufanie, gdy twój zespół potrafi powiedzieć, czyich zdjęć użyto, które rewizje weszły, czy zadanie przyjęto tylko raz, dlaczego dostarczono wynik i jak jest usuwany. Rejestry zgody, klucze idempotencji, własna pamięć i krok przeglądu dają odpowiedzi na te pytania.