WaveSpeedAI

API Genjutsu : soumettre une vidéo de remplacement d'objet

Utilisez l'API Genjutsu pour une requête Object Swap : préparez un clip source, soumettez la tâche et récupérez la vidéo modifiée.

By John7 min read
API Genjutsu : soumettre une vidéo de remplacement d'objet

Une fonctionnalité d’édition vidéo peut renvoyer un job réussi et pourtant laisser votre équipe avec un fichier inutilisable : la mauvaise partie du clip a été traitée, le remplacement bouge d’une image à l’autre, ou personne n’a sauvegardé le résultat. Pour une intégration de l’API Genjutsu, je rendrais chaque modification traçable, de l’entrée jusqu’au fichier approuvé. Le guide de démarrage rapide de l’API de Higgsfield décrit le flux soumission–interrogation–récupération ; ce guide l’applique à une seule requête Object Swap.

Higgsfield fournit le modèle et le endpoint. Si votre produit utilise WaveSpeedAI, consultez son répertoire de modèles pour cette opération précise et son propre schéma de requête. Ne partez pas du principe qu’un autre modèle de remplacement vidéo accepte une requête Higgsfield.

De quoi une requête Genjutsu Object Swap a-t-elle besoin ?

Une requête nécessite l’URL d’une vidéo source et de une à huit URL d’images de référence. Un prompt est facultatif. resolution vaut 720p par défaut ; 480p et 1080p sont également listés. La référence de l’API Object Swap identifie le modèle sous le nom higgsfield/genjutsu/object-swap/v1.0. Elle exige une vidéo d’au moins quatre secondes et d’au moins 409 600 pixels par image.

Vérifiez le clip avant de le soumettre. Les vidéos de plus de 30 secondes sont tronquées à 30 secondes, et la sortie suit cette durée préparée. Si la modification voulue intervient à la seconde 34, une requête réussie ne pourra pas la livrer. Sélectionnez d’abord le segment, puis consignez le segment que vous avez soumis.

Une requête côté serveur peut prendre cette forme. Les URL et les variables d’environnement sont donnés à titre d’illustration :

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"
  }'

Gardez l’identifiant d’accès sur votre serveur. Donnez à chaque modification logique sa propre clé d’idempotence stable, afin qu’une soumission ambiguë puisse être rejouée sans créer volontairement un second job. Si la source montre une personne identifiable, ou utilise des images ou des œuvres protégées, obtenez les droits et les consentements nécessaires avant de la téléverser. Il s’agit d’un rappel de production, pas d’un avis juridique.

Soumettre la modification et suivre son statut

Un POST réussi accepte le travail ; il ne renvoie pas une vidéo terminée. Enregistrez le request_id, le status_url et le cancel_url de la réponse dans l’enregistrement de modification de votre produit. Utilisez ces URL renvoyées au lieu de les construire vous-même.

La documentation sur le cycle de vie des requêtes de Higgsfield liste queued et in_progress comme des états non terminaux. Arrêtez d’attendre lorsque le statut devient completed, failed, nsfw ou canceled. Affichez ces issues séparément dans votre interface. « Traitement en cours » est un mauvais retour lorsque le fournisseur a déjà rejeté le job.

Commencez l’interrogation à intervalles d’environ deux secondes, puis allongez l’intervalle si l’attente se prolonge. Si une vérification de statut rencontre une erreur réseau transitoire, relancez la vérification de statut. Ne soumettez pas un nouveau POST de modification simplement parce qu’une interrogation a échoué. Enregistrez le statut final et toute erreur renvoyée avec l’identifiant de la requête, afin que le support puisse distinguer une génération en échec d’une session de navigateur interrompue trop tôt.

Récupérer et vérifier la vidéo terminée

Lorsque le statut est completed, lisez video.url dans le résultat. Téléchargez le fichier dans un stockage que votre produit contrôle, puis vérifiez qu’il se lit correctement et qu’il correspond à la modification voulue. Un job d’API terminé est un candidat à la livraison, pas une décision d’approbation.

Ne vous contentez pas d’une vignette. Vérifiez le remplacement au début, au milieu et à la fin du clip, en particulier là où l’objet passe derrière un autre sujet ou traverse le cadre. Comparez la durée traitée avec le segment que vous avez soumis. Si le son compte pour la fonctionnalité, inspectez aussi la piste audio de sortie ; la référence Object Swap ne promet pas la conservation de l’audio source.

Un bon résultat isolé ne signifie pas que le workflow de production est prêt. L’achèvement côté fournisseur indique qu’un fichier existe. C’est votre contrôle d’acceptation qui décide si ce fichier peut entrer dans le produit.

Rendre l’Object Swap reproductible en production

Sauvegarder un manifeste de modification rejouable

Conservez ensemble la version de l’asset source, la plage temporelle sélectionnée, les versions des images de référence, le prompt, la résolution, l’ID du modèle, la clé d’idempotence, l’identifiant de la requête et le statut final. Ajoutez l’emplacement de stockage du résultat approuvé. Une personne peut retenir des paramètres. Une équipe, non.

Cet enregistrement est utile lorsqu’un monteur demande « le même remplacement, mais avec le produit bleu ». L’équipe peut modifier une seule entrée de façon délibérée au lieu de reconstituer la requête précédente à partir d’un fichier nommé final-v3.mp4.

Archiver l’original et le résultat approuvé

Conservez le clip original pour pouvoir revenir en arrière, et sauvegardez le résultat approuvé en dehors de l’emplacement média temporaire du fournisseur. Les conditions de l’API sur la conservation et le consentement de Higgsfield indiquent que les médias générés sont disponibles pendant au moins sept jours, mais peuvent être supprimés ensuite. Ce n’est pas une garantie d’URL permanente. Consignez si le résultat a été accepté, rejeté ou renvoyé en révision, et pourquoi.

FAQ

Object Swap conserve-t-il l’audio du clip source ?

La référence Object Swap publiée ne le précise pas. Ne promettez pas la conservation de l’audio dans votre produit. Testez avec un clip autorisé contenant une piste audio reconnaissable, puis inspectez le fichier renvoyé avant d’affirmer cette fonctionnalité.

Une requête Genjutsu en file d’attente peut-elle être annulée ?

Oui, tant qu’elle reste éligible dans la file. Envoyez une demande d’annulation au cancel_url renvoyé ; arrêter simplement votre interrogation n’annule pas le job. Une fois le traitement commencé, l’annulation n’est plus disponible selon le cycle de vie documenté.

Que se passe-t-il si l’URL source expire pendant la préparation ?

La documentation ne précise pas de point d’échec unique pour l’expiration de l’URL d’entrée d’un Object Swap. Gardez la source accessible tant que Higgsfield peut avoir besoin de la récupérer. Si la préparation échoue, consignez le statut et l’erreur réels de la requête. L’acceptation du POST ne prouve pas que le fichier a déjà été téléchargé.

Un échec de préparation de l’entrée consomme-t-il des unités de facturation ?

Cela dépend de l’échec signalé. Les consignes de facturation et de conservation de Higgsfield indiquent que les requêtes se terminant par failed ou nsfw ne sont pas facturées et que les crédits réservés sont remboursés. « Échec de préparation de l’entrée » n’est pas en soi un statut de facturation ; vérifiez donc la réponse et l’enregistrement de facturation plutôt que d’appliquer la même règle à toutes les erreurs de ce type.

Pendant combien de temps l’URL de la vidéo terminée reste-t-elle disponible ?

Les médias générés sont accessibles pendant au moins sept jours et peuvent être supprimés ensuite. Téléchargez rapidement une vidéo approuvée. Pour une fonctionnalité basée sur l’API Genjutsu que les utilisateurs peuvent consulter de nouveau des semaines plus tard, servez la copie sauvegardée depuis votre propre stockage.


Articles précédents :

Partager