Video Head Swap API: Analyse, Zielauswahl und Bearbeitung

Video Head Swap ist ein zweistufiger API-Workflow: Analysieren Sie ein MP4 von 5–30 Sekunden, sehen Sie sich die nummerierten Kopfvorschauen an und senden Sie dann die gewählte Position und die Ersatzporträts an die Bearbeitung. Gesicht, Frisur, Haarfarbe und Kopfform ändern sich; Körper, Garderobe, Bewegung, Audio und alle nicht ausgewählten Personen bleiben wie im Original.

Hier sehen Sie zuerst jeden erfassten Kopf und benennen den gewünschten, bevor Sie für die Bearbeitung bezahlen. Er bearbeitet ein vorhandenes Video; er animiert nicht zwei Standbilder zu einer Darstellung (nutzen Sie dafür ein Bild-zu-Video-Modell).

Die richtige Variante wählen

Face Swap ist die günstigere und einfachere Wahl, wenn die Haare des Originals bleiben können. Der Kopfaustausch lohnt sich, wenn die neue Frisur zur Figur gehört, kostet aber eine Naht am Hals, die Sie prüfen müssen.

Quelle und Referenzporträts vorbereiten

Verwenden Sie nur Abbilder, die Sie bearbeiten dürfen: Ihr eigenes, eine Darstellerin oder einen Darsteller mit unterschriebener Freigabe oder einen generierten Kopf. Alle Sichtbaren müssen Erwachsene sein. Beide Aufrufe sind unzensiert, SpicyAPI fügt also keinen Inhaltsfilter hinzu — diese Prüfung liegt bei Ihnen.

In diesem Beispiel dreht sich eine fiktive erwachsene Person in einer rostfarbenen Jacke während eines zwölfsekündigen Gesprächs zu einem weiteren Erwachsenen. Ersetzen Sie nur den Kopf der ersten Person; die zweite Person, die Kleidung und der Dialog bleiben.

Exportieren Sie die endgültige Quelle vor der Analyse: MP4, bis zu 90 MB, 5–30 Sekunden. video_url erwartet einen öffentlichen HTTPS-Link, der das MP4 selbst zurückgibt, nicht eine HTML-Player-Seite, oder eine spicy://-URI aus dem kostenlosen Upload-Ablauf, der für lokale Dateien der zuverlässigste Weg ist. Wenn Sie die Quelle später schneiden, zuschneiden oder neu kodieren, führen Sie die Analyse erneut aus.

Bereiten Sie 1–3 Porträts derselben erwachsenen Ersatzperson vor. Frontansicht und Dreiviertelansicht sind ein nützliches Ausgangsduo; ergänzen Sie eine Profilansicht, wenn die Quelle eine deutliche Drehung enthält. Haare und scheinbares Alter sollten über den Satz hinweg stimmig sein. Passen Sie auch zum Material: beleuchten Sie die Porträts aus der Richtung, aus der das Bild beleuchtet ist, und mit ähnlicher Kopfwinkelung. An der Naht am Hals zeigt sich eine Abweichung, und kein Request-Feld gleicht das aus. Ganzkörper- und Kleidungsreferenzen gehören zum Figurentausch; dieser Auftrag braucht den vorgesehenen Kopf und die Haare deutlich sichtbar.

Für ein fiktives Referenzbild verwenden Sie ein Briefing wie:

Fotografisches Referenzporträt eines fiktiven erwachsenen Mannes, etwa 35 Jahre alt, mit kurzen dunklen Haaren, gepflegtem Bart und neutralem Ausdruck, in einem vollständig zugeknöpften schlichten Hemd. Weiches gleichmäßiges Licht, freies Gesicht und freie Haare, einfacher Hintergrund. Frontansicht, keine weiteren Personen, kein Text.

Erzeugen Sie die anderen Ansichten aus dieser freigegebenen Identität, statt unabhängig voneinander unverwandte Personen anzufordern. Die Bearbeitung hat kein prompt-Feld, die Referenzen tragen also das gesamte Ergebnis.

Illustration eines Referenzsatzes aus Front-, Dreiviertel- und Profilansicht.

Zuerst im Playground ausprobieren

1. Öffnen Sie die Bearbeitungsseite von Video Head Swap und bleiben Sie im Tab Playground, in der Ansicht Form. Melden Sie sich mit einem Konto mit Guthaben an, um zu starten.
2. Schritt 1, Find the people in your clip. Fügen Sie den Clip unter Input video hinzu (MP4 ablegen oder Asset URL verwenden) und wählen Sie Resolution, 480p oder 720p. Die Bearbeitung muss denselben Wert verwenden, wählen Sie also die Auflösung, die der fertige Clip haben soll. Drücken Sie Find people in this clip ($0.08).
3. Schritt 2, Choose who to replace. Jeder erfasste Kopf erscheint als nummerierte Vorschau. Wählen Sie die gewünschte und fügen Sie ein bis drei Referenzfotos der erwachsenen Ersatzperson hinzu. Setzen Sie einen Seed nur, wenn Sie Referenzsätze fair vergleichen wollen; lassen Sie ihn sonst weg.
4. Starten Sie die Bearbeitung und prüfen Sie dann Kiefer, Hals, Haare und Kragen im Ergebnis mit Ton.

Die Analyse bleibt 24 Stunden lang wiederverwendbar, Sie können also mit denselben Vorschauen einen anderen Referenzsatz ausprobieren, ohne erneut für das Tracking zu zahlen. Jede angenommene Bearbeitung, auch mit neuem Referenzsatz oder Seed, ist eine neue kostenpflichtige Aufgabe. Zeigt keine Vorschau die gewünschte Person, hilft nur ein klarerer Take: Ein nie deutlich sichtbarer Kopf lässt sich nicht tracken, und ein Clip ohne trackbaren Kopf schlägt fehl, wobei die Reservierung freigegeben wird.

Die Analyseseite führt Schritt 1 eigenständig aus; eine erfolgreiche Analyse wird berechnet, auch wenn Sie dort aufhören.

Dann aus dem Code ausführen

Installieren Sie das Python SDK (pip install spicyapi), setzen Sie SPICY_API_KEY in Ihrer Umgebung und speichern Sie dies als swap.py. analyze gibt die Vorschau-URLs aus; edit erwartet die Task-ID der Analyse und die von Ihnen gewählte Vorschau-Position. Die Bearbeitung muss denselben API-Schlüssel und dieselbe Auflösung verwenden wie die Analyse und braucht kein video_url: Sie übernimmt den analysierten Clip.

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

Führen Sie python swap.py analyze aus, öffnen Sie jede Vorschau und notieren Sie die Nummer des gewünschten Erwachsenen (Position 0 ist das erste zurückgegebene Bild, keine Links-nach-rechts-Regel; fallen Sie nie auf 0 zurück, wenn Ihre Person fehlt), dann python swap.py edit <analysis_task_id> 1. Die Bearbeitung verarbeitet 1 bis 10 Ziele mit je 1 bis 3 Referenzbildern derselben Person; Maske, Outfit, Audio oder Prompt-Eingaben gibt es nicht. Anlegen, Warten, Wiederholungen, Idempotency Keys und Downloads stehen im Tasks-Leitfaden und in der Python SDK Referenz; eine lokale Datei läuft über den kostenlosen Upload-Ablauf und kommt als spicy://-URI für video_url zurück.

Oder einen Agenten ausführen lassen

Wenn ein Assistent die beiden Aufrufe ausführen soll, zeigen alle drei offiziellen Tools den Preis und fragen nach einem kostenpflichtigen Aufruf.

• CLI. Legen Sie das input-Objekt der Analyse (video_url, resolution) in analysis.json und führen Sie dann aus:

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

Führen Sie die Bearbeitung genauso mit edit.json aus. Siehe die CLI-Doku; npx @spicyapi/cli funktioniert ohne Installation.

• MCP-Server. Fügen Sie den MCP-Server hinzu und fragen Sie dann: "Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." Er lädt die Datei mit spicyapi_upload_file hoch, ruft spicyapi_task_create auf, das für Ihre Preisfreigabe anhält, und dann spicyapi_task_wait. Wählen Sie die Position selbst und lassen Sie dann die Bearbeitung ausführen.
• Skill. npx skills add spicyapi-ai/spicy-skill installiert den Agent Skill, der einen Coding-Assistenten das aktuelle Modell-Schema lesen lässt, statt Felder zu raten.

Wie eine fertige Bearbeitung aussieht

Das veröffentlichte Modellbeispiel unten ist ein zehnsekündiger Quellclip und dessen 480p-Bearbeitung mit einem Referenzporträt. Haare und Gesicht ändern sich; Kleid, Schritt, Gegenlicht und Kamera bleiben. Prüfen Sie zuerst Kiefer und Halslinie, wo sich eine Abweichung in Licht oder Winkel zeigt.

Was es kostet

Die Bearbeitung kostet $0.064 pro abgerechneter Sekunde bei 480p und $0.12 bei 720p. Die Abrechnung läuft in Fünf-Sekunden-Blöcken, mit einem Minimum von fünf Sekunden und einer Obergrenze von dreißig Sekunden. Ein 10-Sekunden-Clip in 480p kostet insgesamt $0.72: $0.08 Analyse plus $0.64 Bearbeitung.

Vor der Abrechnung reserviert die Bearbeitung das Maximum von dreißig Sekunden, $1.92 bei 480p oder $3.60 bei 720p. Ein zwölfsekündiger Clip in 720p wird mit $3.60 reserviert, obwohl die Bearbeitung $1.80 kostet; der Rest wird freigegeben, wenn die Task abgerechnet wird.

Auswahl, Identität und Auslieferung getrennt prüfen

Illustration der Prüfung von Haaren, Kragen und einer Hand im Vordergrund.

Spielen Sie das zurückgegebene Video mit Ton ab. Die Bearbeitung behält Quellaudio und Körperbewegung; sie ändert nicht die Stimme der sprechenden Person, und die Kulisse ist nicht garantiert pixelgenau identisch. Prüfen Sie auch die nicht ausgewählte Person, besonders beim Vorbeikreuzen. Wenn eine Hand das ersetzte Gesicht kreuzt, gehen Sie die Berührung und das Wiederauftauchen Frame für Frame durch, statt nur ein attraktives erstes Bild freizugeben.

Speichern Sie das angenommene Video sofort in Ihrem eigenen Speicher: Ergebnislinks halten etwa 20 Minuten und Ergebnisse werden höchstens 14 Tage aufbewahrt, eine Analyse-ID, ein Vorschaubild und eine temporäre Medien-URL sind also keine dauerhafte Kopie.