Genjutsu API: Ein Objektaustausch-Video einreichen
Verwenden Sie die Genjutsu API für eine einzelne Object-Swap-Anfrage: Bereiten Sie einen Quellclip vor, senden Sie den Auftrag ab und rufen Sie das bearbeitete Video ab.

Ein Videobearbeitungs-Feature kann einen erfolgreichen Job zurückgeben und Ihrem Team trotzdem ein unbrauchbares Asset hinterlassen: Es wurde der falsche Teil des Clips verarbeitet, der Ersatz verschiebt sich zwischen den Frames, oder niemand hat die Ausgabe gespeichert. Bei einer Genjutsu API-Integration würde ich jede Bearbeitung vom Input bis zur freigegebenen Datei nachvollziehbar machen. Die API-Kurzanleitung von Higgsfield beschreibt den Ablauf aus Absenden, Abfragen und Abrufen; dieser Leitfaden wendet ihn auf eine einzelne Object-Swap-Anfrage an.
Higgsfield stellt das Modell und den Endpunkt bereit. Wenn Ihr Produkt WaveSpeedAI verwendet, prüfen Sie im Modellverzeichnis, ob es genau diese Operation gibt, und lesen Sie das zugehörige Request-Schema. Gehen Sie nicht davon aus, dass ein anderes Video-Swap-Modell eine Higgsfield-Anfrage akzeptiert.

Was benötigt eine einzelne Genjutsu-Object-Swap-Anfrage?
Eine Anfrage benötigt eine Quellvideo-URL und ein bis acht Referenzbild-URLs. Ein Prompt ist optional. resolution ist standardmäßig 720p; 480p und 1080p sind ebenfalls aufgeführt. Die Object-Swap-API-Referenz nennt das Modell higgsfield/genjutsu/object-swap/v1.0. Es erfordert ein Video von mindestens vier Sekunden Länge und mindestens 409.600 Pixeln pro Frame.
Prüfen Sie den Clip, bevor Sie ihn absenden. Videos, die länger als 30 Sekunden sind, werden auf 30 Sekunden gekürzt, und die Ausgabe folgt dieser aufbereiteten Dauer. Wenn die gewünschte Bearbeitung bei Sekunde 34 stattfindet, kann auch eine erfolgreiche Anfrage sie nicht liefern. Wählen Sie zuerst das Segment aus und halten Sie dann fest, welches Segment Sie eingereicht haben.
Eine serverseitige Anfrage kann diese Form haben. Die URLs und Umgebungsvariablen dienen nur als Beispiel:
curl -X POST \
"https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
-H "Authorization: Key ${HF_KEY}" \
-H "Idempotency-Key: ${EDIT_ID}" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/approved-source.mp4",
"image_urls": ["https://example.com/approved-object.png"],
"prompt": "Replace the featured cup with the reference cup.",
"resolution": "720p"
}'
Behalten Sie die Zugangsdaten auf Ihrem Server. Vergeben Sie für jede logische Bearbeitung einen eigenen, stabilen Idempotency-Key, damit eine nicht eindeutige Übermittlung erneut versucht werden kann, ohne absichtlich einen zweiten Job zu erzeugen. Zeigt die Quelle eine identifizierbare Person oder verwendet sie geschütztes Filmmaterial oder geschützte Grafiken, holen Sie vor dem Hochladen die erforderlichen Rechte und Einwilligungen ein. Dies ist ein Hinweis für den Produktivbetrieb, keine Rechtsberatung.
Die Bearbeitung absenden und den Status verfolgen
Ein erfolgreicher POST nimmt die Arbeit an; er liefert noch kein fertiges Video. Speichern Sie request_id, status_url und cancel_url aus der Antwort im Bearbeitungsdatensatz Ihres Produkts. Verwenden Sie diese zurückgegebenen URLs, statt sie selbst zusammenzubauen.
Die Dokumentation zum Request-Lebenszyklus von Higgsfield führt queued und in_progress als nicht-terminale Zustände auf. Hören Sie auf zu warten, sobald der Status completed, failed, nsfw oder canceled lautet. Zeigen Sie diese Ergebnisse in Ihrer Oberfläche getrennt an. „Wird noch verarbeitet“ ist ein schlechtes Feedback, wenn der Anbieter den Job bereits abgelehnt hat.

Beginnen Sie mit dem Polling in Abständen von etwa zwei Sekunden und vergrößern Sie das Intervall bei längerer Wartezeit. Tritt bei einer Statusabfrage ein vorübergehender Netzwerkfehler auf, wiederholen Sie die Statusabfrage. Senden Sie nicht einen weiteren POST für eine Bearbeitung, nur weil eine Abfrage fehlgeschlagen ist. Speichern Sie den endgültigen Status und jeden zurückgegebenen Fehler zusammen mit der Request-ID, damit der Support eine fehlgeschlagene Generierung von einer vorzeitig beendeten Browsersitzung unterscheiden kann.
Das fertige Video abrufen und prüfen
Lautet der Status completed, lesen Sie video.url aus dem Ergebnis. Laden Sie die Datei in einen Speicher herunter, den Ihr Produkt kontrolliert, und prüfen Sie dann, ob sie abspielbar ist und zur beabsichtigten Bearbeitung passt. Ein abgeschlossener API-Job ist ein Kandidat für die Auslieferung, keine Freigabeentscheidung.
Prüfen Sie mehr als ein Vorschaubild. Kontrollieren Sie den Ersatz am Anfang, in der Mitte und am Ende des Clips, besonders dort, wo sich das Objekt hinter ein anderes Motiv bewegt oder den Bildausschnitt durchquert. Vergleichen Sie die verarbeitete Dauer mit dem Segment, das Sie eingereicht haben. Wenn Ton für das Feature wichtig ist, prüfen Sie auch die Audiospur der Ausgabe; die Object-Swap-Referenz verspricht nicht, dass der Quellton erhalten bleibt.
Eine gute einzelne Ausgabe bedeutet nicht, dass der Produktions-Workflow bereit ist. Die Fertigmeldung des Anbieters besagt, dass eine Datei existiert. Ihre Abnahmeprüfung entscheidet, ob diese Datei in das Produkt übernommen werden darf.
Den Object Swap in der Produktion reproduzierbar machen
Ein wiederholbares Bearbeitungsmanifest speichern
Bewahren Sie die Version des Quell-Assets, den gewählten Zeitbereich, die Versionen der Referenzbilder, den Prompt, die Auflösung, die Modell-ID, den Idempotency-Key, die Request-ID und den endgültigen Status zusammen auf. Ergänzen Sie den Speicherort der freigegebenen Ausgabe. Eine einzelne Person kann sich Parameter merken. Ein Team kann das nicht.
Dieser Datensatz hilft, wenn ein Editor „denselben Swap, aber mit dem blauen Produkt“ verlangt. Das Team kann dann gezielt eine Eingabe ändern, statt die vorherige Anfrage aus einer Datei namens final-v3.mp4 zu rekonstruieren.
Original und freigegebene Ausgabe archivieren
Bewahren Sie den Originalclip für ein Rollback auf und speichern Sie das freigegebene Ergebnis außerhalb des temporären Medienspeichers des Anbieters. Die API-Bedingungen zu Aufbewahrung und Einwilligung von Higgsfield besagen, dass generierte Medien mindestens sieben Tage lang verfügbar sind, danach aber gelöscht werden können. Das ist keine Garantie für eine dauerhafte URL. Halten Sie fest, ob das Ergebnis angenommen, abgelehnt oder zur Überarbeitung zurückgegeben wurde, und warum.
FAQ

Behält Object Swap den Ton des Quellclips bei?
Die veröffentlichte Object-Swap-Referenz sagt dazu nichts. Versprechen Sie in Ihrem Produkt keine Audio-Durchleitung. Testen Sie mit einem autorisierten Clip, der eine gut erkennbare Audiospur enthält, und prüfen Sie die zurückgegebene Datei, bevor Sie diese Funktion zusichern.
Kann eine eingereihte Genjutsu-Anfrage abgebrochen werden?
Ja, solange sie in der Warteschlange noch infrage kommt. Senden Sie eine Abbruchanfrage an die zurückgegebene cancel_url; allein das Beenden Ihres Pollers bricht den Job nicht ab. Sobald die Verarbeitung begonnen hat, ist ein Abbruch laut dokumentiertem Lebenszyklus nicht mehr möglich.
Was passiert, wenn die Quell-URL während der Aufbereitung abläuft?
Die Dokumentation nennt für eine ablaufende Object-Swap-Eingabe-URL keinen allgemeingültigen Fehlerzeitpunkt. Halten Sie die Quelle erreichbar, solange Higgsfield sie möglicherweise abrufen muss. Schlägt die Aufbereitung fehl, protokollieren Sie den tatsächlichen Anfragestatus und den Fehler. Dass der POST angenommen wurde, beweist nicht, dass die Datei bereits heruntergeladen war.
Verbraucht ein Fehler bei der Eingabeaufbereitung Abrechnungseinheiten?
Das hängt vom gemeldeten Fehler ab. Die Hinweise zu Abrechnung und Aufbewahrung von Higgsfield besagen, dass Anfragen, die mit failed oder nsfw enden, nicht berechnet und reservierte Credits erstattet werden. „Fehler bei der Eingabeaufbereitung“ ist selbst kein Abrechnungsstatus; prüfen Sie daher die Antwort und den Abrechnungsdatensatz, statt jedem solchen Fehler dieselbe Regel zuzuweisen.
Wie lange bleibt die URL des fertigen Videos verfügbar?
Generierte Medien sind mindestens sieben Tage lang abrufbar und können danach entfernt werden. Laden Sie ein freigegebenes Video zeitnah herunter. Für ein Genjutsu API-Feature, das Nutzer auch Wochen später erneut aufrufen können, sollten Sie die gespeicherte Kopie aus Ihrem eigenen Speicher ausliefern.
Vorherige Beiträge:
/filters:quality(82)/media/images/1773962750383987480_n3hqzHRZ.webp)
/filters:quality(82)/media/images/3439779b-d7cf-42fd-958d-8711fe2abdf4.webp)