Introduction
Video Head Swap Analysis lit un plan et renvoie une vignette par tête qu’il parvient à suivre, dans un ordre fixe : la première image est la position 0, la deuxième la position 1, et ainsi de suite. Ce sont ces positions que prend l’appel de remplacement : vous regardez les images, puis vous renvoyez les numéros.
Rien n’est généré ici et le plan n’est pas modifié. Cet appel produit la liste de cibles sur laquelle travaille l’appel de remplacement, et c’est le seul moyen de savoir combien de têtes figurent dans un plan et laquelle est laquelle.
Fonctionnalités et points forts
Vous choisissez sur images, pas sur coordonnées
La plupart des endpoints de remplacement vous demandent de décrire la personne visée, ou bien ils devinent. Ici, l’analyse vous remet les candidats sous forme d’images numérotées. L’ambiguïté sur la personne à remplacer est levée avant que quoi que ce soit ne soit généré, c’est-à-dire au moment où une erreur ne coûte encore rien.
Une analyse alimente plusieurs remplacements
Le résultat reste exploitable pendant 24 heures. Distribuez un rôle, regardez le rendu, puis envoyez un autre jeu de photos de référence sur la même analyse : l’analyse n’est facturée qu’une fois. Passé 24 heures, les références expirent et le plan doit être analysé de nouveau.
Lit le métrage tel qu’il a été tourné
Le suivi accompagne chaque tête à travers les coupes, les changements d’axe et les occultations partielles. Les plans de 5 à 30 secondes sont acceptés, et l’analyse signale toutes les têtes qu’elle parvient à tenir sur la durée du plan, pas seulement celle qui est au premier plan.
Paramètres de requête
| Paramètre | Obligatoire | Description |
|---|---|---|
video_url | Oui | Le plan à analyser, 5 à 30 secondes. Gardez cette URL exacte : l’appel de remplacement doit porter sur la même vidéo, et elle y est reprise automatiquement si vous l’omettez. 1 caractères minimum |
resolution | Non | Résolution de suivi. L’appel de remplacement doit utiliser la même valeur, choisissez donc celle que doit avoir le plan terminé. |
Tarification
$0.08 / analyse
L’analyse et le remplacement sont facturés séparément.
Cas d’utilisation
Vérifier un plan avant de payer pour le remplacer
L’appel de remplacement coûte plus cher que l’analyse. Analyser d’abord vous dit si les têtes qui vous intéressent sont réellement suivables dans ce métrage : flou marqué, occultations longues et sujets qui sortent du cadre se traduisent par une vignette manquante ou instable.
Désigner une personne dans une foule
Analysez une scène où plusieurs personnes sont à l’image, lisez les vignettes et ne renvoyez que la position visée. Le remplacement laisse toutes les autres intactes.
Garder la même distribution sur toute une série
Générez un lot de plans avec n’importe quel modèle vidéo, analysez-les un par un et servez-vous des vignettes pour aligner la même cible dans chaque plan, afin que la série se lise d’un seul tenant.
Tout sujet, avec un interprète consentant
Rien ne change dans la requête, quel que soit le contenu des images. L’exigence d’autorisation décrite dans les limites plus bas ne change pas non plus : c’est une condition ferme, pas une classification de contenu.
Guide de prompt et conseils pratiques
Utilisez la même résolution dans les deux appels
Choisissez la résolution que doit avoir le plan terminé et employez-la aussi ici : l’appel de remplacement devra tourner à la même valeur. Elle ne change pas ce que cet appel détecte, seulement le cadre dans lequel travaille le remplacement.
Lisez l’ordre des vignettes, ne le supposez pas
Les images reviennent ordonnées, mais l’ordre reflète le suivi, pas la place à l’écran ni l’importance. La personne la plus à gauche n’est pas forcément la position 0. Regardez les images.
Envoyez la même vidéo aux deux appels
L’appel de remplacement exige un plan identique : même fichier, même encodage. Omettez video_url dans la requête de remplacement et elle est reprise de l’analyse, ce qui reste le moyen le plus sûr de garantir qu’ils correspondent.
Analysez de nouveau si le métrage change
Réencoder, couper ou réexporter le plan invalide l’analyse : les positions ne désignent plus les mêmes têtes. Analysez le fichier que vous allez réellement remplacer.
Démarrage rapide de l’API
# 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"
La référence API détaille l’authentification, le schéma complet, le polling et la gestion des erreurs.
