Video Character Swap: Referenzen, Zielauswahl und Prüfung

Nutzen Sie Character Swap, wenn der Ersatz das gesamte Aussehen einer Person verändern soll, einschließlich Statur und Kleidung, während Szene, Kamerabewegung und Originalton unverändert bleiben. Character Swap lässt Sie auswählen, welche Person im Clip ausgetauscht wird: Analysieren Sie den finalen Clip, prüfen Sie die nummerierten Vorschauen und reichen Sie dann den gewählten Vorschau-Index mit ein bis drei Bildern der Ersatzperson ein. Soll die ursprüngliche Kleidung erhalten bleiben, nutzen Sie stattdessen einen Head- oder Face-Workflow.

Bei SpicyAPI sind Analyse und Bearbeitung getrennte kostenpflichtige Aufgaben. Eine sieben Sekunden lange Quelle kostet insgesamt $0.72 bei 480p oder $1.28 bei 720p: eine Analyse plus die Bearbeitung, die auf zehn Sekunden aufgerundet wird. Der Playground führt beide Schritte im Browser aus, und die API nimmt dieselben Eingaben. Sie benötigen eine Genehmigung für das Material und für die Ähnlichkeit in den Referenzbildern.

Eine sieben Sekunden lange Szene und einen Ganzkörper-Ersatz vorbereiten

Unser Beispiel ist ein sieben Sekunden langer Shot, in dem jemand einen geschlossenen Werkzeugkasten zu einer Werkbank trägt, während ein anderer Erwachsener danebensteht. Die tragende Person wird durch eine fiktive erwachsene Figur in marineblauer Arbeitsjacke und anthrazitfarbener Hose ersetzt, also um das Aussehen aus den Illustrationen unten. Werkbank, Werkzeugkasten, die andere Person und die ursprüngliche Darstellung bleiben.

Exportieren Sie exakt die sieben Sekunden lange Quelle, die Sie bearbeiten wollen. Behalten Sie den anfänglichen Griff, das Tragen und das Loslassen, nachdem der Werkzeugkasten die Werkbank erreicht hat. Die Eingabe ist 5–30 Sekunden MP4 bis zu 90 MB. Das Hochladen der Datei ist der zuverlässigste Weg; ein direkter Link muss auf die MP4-Datei selbst zeigen, weil eine Seite mit einem Player scheitert (die Gebühr wird erstattet). Kürzen oder Neukodieren nach der Analyse erfordert eine neue Analyse.

Der Tracker folgt Personen, die groß und sichtbar bleiben, schneiden Sie also auf den entscheidenden Abschnitt und vermeiden Sie lange Zeiten, in denen die gewünschte Person vollständig verdeckt ist. Ein kürzerer Schnitt kostet auch weniger, da die Bearbeitung in Fünf-Sekunden-Blöcken abgerechnet wird.

Für den Ersatz bereiten Sie eine Front- und eine Dreiviertel-Ganzkörperansicht derselben erwachsenen Person im selben Outfit vor. Eine klare Referenz wird akzeptiert; drei sind das Maximum pro Ziel. Ein Kopf-und-Schulter-Porträt lässt Körperbau und Kleidung zur Vermutung, zeigen Sie deshalb Ärmel, Hände und Schuhe und beleuchten Sie die Referenzen wie das Material, statt das schärfste Porträt zu wählen. Kombinieren Sie nicht das Gesicht einer Person, die Hose einer anderen und eine andere Jacke im dritten Bild. Der Dienst empfängt diese als Referenzen für einen Ersatz, nicht als separat zugewiesene Kleidungsschichten.

Ein brauchbares Briefing für die Bilderzeugung lautet:

Ganzkörper-Referenzporträt einer fiktiven erwachsenen Frau, etwa 30, in einer schlichten marineblauen Arbeitsjacke, anthrazitfarbener Hose und dunklen flachen Schuhen. Frontale, entspannte Haltung, Hände sichtbar, Ärmel und Schuhe lesbar, neutraler Hintergrund. Kein Werkzeugkasten, keine anderen Personen, keine Schrift.

Erzeugen oder fotografieren Sie bei Bedarf einen zweiten Blickwinkel desselben etablierten Designs. Die Character-Swap-Bearbeitung hat kein Text-Prompt-Feld, kein Kleidungsauswahlfeld und keine Körpermaske, daher muss die gewünschte Kleidung in den Referenzbildern enthalten sein.

Illustration eines Ganzkörper-Referenzsatzes aus Front- und Dreiviertelansicht.

Zuerst im Playground ausprobieren

1. Öffnen Sie die Seite des Modells Video Character Swap und bleiben Sie im Tab Playground in der Ansicht Form. Melden Sie sich mit einem Konto mit Guthaben an, um zu starten.
2. Legen Sie in Step 1, Find the people in your clip die sieben Sekunden lange MP4 unter Input video ab (Hochladen ist zuverlässiger als ein Link) und wählen Sie die Resolution, die der fertige Clip haben soll, 480p oder 720p. Die Bearbeitung muss denselben Wert verwenden.
3. Drücken Sie Find people in this clip ($0.08). Jede gefundene Person erscheint in Step 2, Choose who to replace, als eine zugeschnittene Vorschau pro Person.
4. Wählen Sie die Vorschau der Person, die den Werkzeugkasten trägt, fügen Sie ein bis drei Referenzbilder der Ersatzperson hinzu und starten Sie die Bearbeitung. Ein Seed ist optional.

Position 0 ist die erste zurückgegebene Vorschau, nicht notwendigerweise die linke oder größte Person, weil die Reihenfolge aus dem Tracking stammt und nicht aus der Bildschirmposition. Ist die tragende Person die zweite Vorschau, ist das Index 1. Behalten Sie die zurückgegebene Reihenfolge, wenn Sie Vorschauen speichern: alphabetische Dateinamen oder eine sortierte Galerie können den Index unbemerkt ändern.

Wenn die vorgesehene tragende Person keine Vorschau hat, zahlen Sie nicht für eine Bearbeitung, indem Sie eine benachbarte Zahl raten. Kein Referenzbild kann eine Person ohne Vorschau zurückbringen, verwenden Sie also ein Take, in dem diese Person klar sichtbar ist. Eine Analyse, die niemanden findet, endet als fehlgeschlagen und ihre Reservierung wird freigegeben; eine erfolgreiche Analyse wird berechnet, auch wenn Sie sich entscheiden, nicht zu tauschen.

Dann aus dem Code aufrufen

Installieren Sie das Python SDK (pip install spicyapi), setzen Sie SPICY_API_KEY und führen Sie Folgendes aus. Es lädt den Clip und zwei Referenzen hoch, führt die Analyse aus, gibt die Vorschau-Links aus, fragt nach dem zu tauschenden Index und reicht dann die Bearbeitung ein. Beide Aufgaben werden berechnet.

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

Uploads, Warten, Fehler und Wiederholungen stehen in der Anleitung zu Subject Swap, der Task-Dokumentation und der Python SDK-Referenz. Verwenden Sie für beide Schritte denselben API-Schlüssel und führen Sie die Bearbeitung innerhalb von 24 Stunden nach der Analyse aus (ein hochgeladener Clip läuft ebenfalls nach einem Tag ab); eine Analyse kann mehrere separat berechnete Bearbeitungen versorgen. Personen, die Sie nicht auflisten, bleiben unangetastet, und ein Index gehört zu dieser Analyse, verwenden Sie ihn also nicht als Charakter-ID in einem anderen Shot.

Ein Ganzkörper-Ersatz soll Szene, Kamerabewegung, Choreografie und Originalton erhalten. Dieser Umfang verspricht keine unveränderten Hintergrundpixel und keine neue Stimme.

Oder einen Agenten das ausführen lassen

Wenn ein Assistent den Swap ausführen soll, geben Sie ihm die CLI oder den MCP-Server. Beide zeigen den Preis und fragen vor einem kostenpflichtigen Aufruf nach Ihrer Bestätigung. Der Skill fügt Anweisungen für beides obendrauf.

• CLI. spicyapi führt einen Task aus einem Terminal aus (npx @spicyapi/cli funktioniert ohne Installation):

``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 enthält {"video_url": "spicy://...", "resolution": "720p"}. Sehen Sie sich die Vorschauen an und führen Sie dann den Befehl mit video-edit, dem eigenen Schlüssel workshop-edit-v1 und einer input.json aus, die analysis_task_id, resolution und swap_targets enthält. Verwenden Sie einen Schlüssel nur für eine unveränderte Anfrage; eine neue Quelle, ein neues Ziel oder ein neuer Referenzsatz braucht einen neuen Schlüssel.

• MCP-Server. Fügen Sie Ihrem Assistenten den MCP-Server hinzu (das Konfigurationsbeispiel steht auf dieser Seite) und fragen Sie dann: "Analysiere ./workshop-seven-seconds.mp4 mit Character Swap bei 720p und zeige mir die Vorschauen." Nachdem Sie die Person gewählt haben, sagen Sie: "Ersetze Index 1 mit ./replacement-front.png und ./replacement-three-quarter.png." Er ruft spicyapi_upload_file, dann spicyapi_task_create (das für Ihre Preisbestätigung stoppt), dann spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installiert den Agent Skill, der einem Coding-Assistenten beibringt, das aktuelle Schema zu lesen und Idempotenzschlüssel wiederzuverwenden. Er kann keine Tasks selbst ausführen, nutzen Sie ihn also zusammen mit CLI oder MCP. Welche Vorschau getauscht wird, bleibt Ihre Entscheidung.

Die Kosten verstehen, bevor Sie Varianten erstellen

Die Preise stammen aus dem öffentlichen Katalog (Oktober 2026).

Die Bearbeitungsdauer wird auf volle Fünf-Sekunden-Blöcke aufgerundet, mit einem Minimum von fünf Sekunden und einer Obergrenze von dreißig Sekunden. Eine 5-Sekunden-Quelle nutzt einen Block; 5,1 Sekunden nutzen zwei. Vor dem Einreichen reserviert die Bearbeitungsschätzung das Maximum von dreißig Sekunden, $1.92 bei 480p oder $3.60 bei 720p, und die Differenz wird zurückgegeben, wenn der Task abgeschlossen ist. Eine Budgetprüfung muss daher die Reservierung zulassen, nicht nur den erwarteten Endbetrag. Eine bei der Erstellung abgelehnte Anfrage (abweichende Auflösung, falsche Analyse-ID, wiederholter Index) erzeugt und berechnet nichts.

Zwei 720p-Bearbeitungen der sieben Sekunden langen Quelle unter Wiederverwendung einer Analyse kosten insgesamt $2.48: $0.08 plus zweimal $1.20. Das Ändern von Referenzen oder Seed ist eine neue kostenpflichtige Bearbeitung, keine kostenlose Revision.

Das richtige Problem beheben

Illustration der Prüfung eines Ausdrucks.

Beobachten Sie die tragende Person, den Werkzeugkasten und den nicht ausgewählten Erwachsenen zusammen in normaler Geschwindigkeit. Prüfen Sie dann Griff, Werkbankkontakt und Loslassen. Ein neues Gesicht kann hervorragend aussehen, während die zentrale Handlung scheitert. Hat nur die letzte halbe Sekunde einen Fehler, kann Kürzen genügen; ist der Griff durchgehend kaputt, wählen Sie eine klarere Quelle oder nutzen Sie einen engeren Kopf-Ersetzungsumfang, wenn der ursprüngliche Körper und die Kleidung bleiben können.

Kopieren Sie den akzeptierten Clip in Ihren eigenen Speicher, bevor er abläuft: Ergebnisse werden etwa 14 Tage aufbewahrt (siehe Medienaufbewahrung und -zustellung).