Einführung
Video Head Swap Analysis liest einen Clip und gibt pro Kopf, den es verfolgen kann, ein Vorschaubild zurück, in fester Reihenfolge: Das erste Bild ist Position 0, das zweite Position 1 und so fort. Genau diese Positionen nimmt der Tausch-Aufruf entgegen. Sie sehen sich die Bilder an und senden die Nummern zurück.
Hier entsteht nichts Neues, und am Clip ändert sich nichts. Dieser Aufruf erzeugt die Zielliste, mit der der Tausch-Aufruf arbeitet, und er ist der einzige Weg herauszufinden, wie viele Köpfe in einer Einstellung sind und welcher davon welcher ist.
Wichtige Funktionen und Highlights
Auswahl über Bilder statt über Koordinaten
Bei den meisten Tausch-Endpunkten müssen Sie beschreiben, wen Sie meinten, oder der Endpunkt rät. Hier reicht Ihnen die Analyse die Kandidaten als nummerierte Bilder. Die Frage, wer ersetzt wird, ist geklärt, bevor überhaupt etwas erzeugt wird – also genau zu dem Zeitpunkt, an dem ein Irrtum noch nichts kostet.
Eine Analyse trägt mehrere Tausch-Aufrufe
Das Ergebnis bleibt 24 Stunden lang nutzbar. Besetzen Sie eine Rolle, sehen Sie sich das Ergebnis an und schicken Sie dann einen anderen Satz Referenzfotos gegen dieselbe Analyse: Bezahlt wird die Analyse nur einmal. Nach 24 Stunden verfallen die Referenzen, und der Clip muss erneut analysiert werden.
Liest das Material so, wie es gedreht wurde
Das Tracking folgt jedem Kopf über Schnitte, Drehungen und teilweise Verdeckung hinweg. Clips von 5 bis 30 Sekunden werden angenommen, und die Analyse meldet jeden Kopf, den sie über die Länge der Einstellung halten kann, nicht nur den vordersten.
Request-Parameter
| Parameter | Pflicht | Beschreibung |
|---|---|---|
video_url | Ja | Der zu analysierende Clip, 5 bis 30 Sekunden. mindestens 1 Zeichen |
resolution | Nein | Die Tracking-Auflösung. Der Tausch-Aufruf muss denselben Wert verwenden, wählen Sie also die Auflösung, die der fertige Clip haben soll. |
Preis
$0.08 / Analyse
Analyse und Austausch werden getrennt berechnet.
Anwendungsfälle
Einen Clip prüfen, bevor Sie für den Tausch bezahlen
Der Tausch-Aufruf kostet mehr als die Analyse. Eine vorgeschaltete Analyse sagt Ihnen, ob die Köpfe, auf die es Ihnen ankommt, in diesem Material überhaupt verfolgbar sind: starke Unschärfe, lange Verdeckungen und Motive, die das Bild verlassen, zeigen sich als fehlendes oder unstetes Vorschaubild.
Eine Person aus der Menge auswählen
Analysieren Sie eine Szene mit mehreren Personen im Bild, sehen Sie sich die Vorschaubilder an und senden Sie nur die gemeinte Position zurück. Alle anderen bleiben vom Tausch unberührt.
Eine Besetzung über eine ganze Serie halten
Erzeugen Sie eine Reihe von Clips mit einem beliebigen Videomodell, analysieren Sie jeden einzeln und richten Sie anhand der Vorschaubilder in jeder Einstellung dasselbe Ziel aus, damit die Serie durchgehend wirkt.
Jedes Motiv, mit einwilligenden Darstellern
An der Anfrage ändert sich nichts, egal was das Material zeigt. Die Autorisierungspflicht in den Grenzen weiter unten ändert sich ebenso wenig: Sie ist eine harte Bedingung, keine Inhaltseinstufung.
Prompt-Leitfaden und Praxistipps
In beiden Aufrufen dieselbe Auflösung verwenden
Wählen Sie die Auflösung, die der fertige Clip haben soll, und verwenden Sie sie auch hier: Der Tausch-Aufruf muss mit demselben Wert laufen. Sie ändert nicht, was dieser Aufruf erkennt, sondern nur das Bild, in dem der Tausch arbeitet.
Die Reihenfolge der Vorschaubilder lesen, nicht annehmen
Die Bilder kommen geordnet zurück, aber die Reihenfolge ergibt sich aus dem Tracking, nicht aus der Lage im Bild und nicht aus der Wichtigkeit. Die Person ganz links im Bild ist nicht zwangsläufig Position 0. Sehen Sie sich die Bilder an.
Beiden Aufrufen dasselbe Video geben
Der Tausch-Aufruf braucht denselben Clip: dieselbe Datei, dieselbe Kodierung. Lassen Sie video_url in der Tausch-Anfrage weg, dann wird die URL aus der Analyse übernommen, und das ist der sicherste Weg, dass beide übereinstimmen.
Erneut analysieren, wenn sich das Material ändert
Neu kodieren, kürzen oder neu exportieren macht die Analyse ungültig: Die Positionen zeigen dann nicht mehr auf dieselben Köpfe. Analysieren Sie die Datei, die Sie tatsächlich tauschen werden.
API-Schnellstart
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/head-swap-video-v1/video-analyze",
"input": {
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Authentifizierung, vollständiges Schema, Polling und Fehlerbehandlung stehen in der API-Referenz.
