Introduction
Video Head Swap reçoit l’identifiant de tâche d’une analyse, les positions retenues parmi ses vignettes et une à trois photos de référence pour chacune, puis renvoie le plan avec ces têtes remplacées. Cheveux, forme de la tête et identité changent ; le corps, les costumes, le mouvement, le cadre et la bande son d’origine restent tels qu’ils ont été tournés. Les têtes non listées ne sont pas touchées.
Video Head Swap tient en deux appels. Le premier suit chaque tête dans un plan de 5 à 30 secondes et renvoie une vignette par tête, dans un ordre fixe. Le second reçoit les positions retenues et une à trois photos de référence pour chacune, puis renvoie le plan avec ces têtes remplacées et la bande son d’origine intacte.
Fonctionnalités et points forts
C’est vous qui désignez la personne
La plupart des endpoints de ce type doivent deviner qui vous vouliez dire. Ici, le premier appel vous montre chaque tête trouvée, numérotée, et le second ne touche qu’aux numéros que vous renvoyez. Sur un plan à quatre personnes, vous en changez une et les trois autres restent exactement telles qu’elles ont été tournées.
Gardez la vidéo et la résolution identiques
Video Head Swap n’est pas un endpoint mais une paire. Le premier appel, video-analyze, suit toutes les têtes d’un plan de 5 à 30 secondes et renvoie une vignette par tête dans un ordre fixe, facturée au forfait par requête quelles que soient la durée du plan et le nombre de têtes trouvées. Le second appel, video-edit, reçoit l’identifiant de tâche de cette analyse, les positions retenues et une à trois photos de référence pour chacune, puis renvoie un plan unique dont la bande son d’origine est conservée, facturé à la seconde de métrage en 480p ou 720p. Les données de suivi elles-mêmes ne vous sont jamais exposées : vous travaillez avec votre propre identifiant de tâche et avec des positions numérotées à partir de zéro, qui correspondent exactement aux vignettes qui vous ont été montrées. Les deux appels doivent porter sur la même vidéo et la même résolution ; en cas d’écart, le second appel est refusé plutôt que laissé passer en silence.
Paramètres de requête
| Paramètre | Obligatoire | Description |
|---|---|---|
analysis_task_id | Oui | L’identifiant de tâche de l’appel d’analyse de ce plan. Ses vignettes sont listées dans le même ordre que |
swap_targets | Oui | Une entrée par tête à remplacer ; les têtes omises ne sont pas touchées. |
video_url | Non | Facultatif. Omettez-le et la vidéo de l’analyse est utilisée. 1 caractères minimum |
resolution | Non | Doit correspondre à la résolution de l’analyse. C’est aussi ce champ qui détermine le palier tarifaire. |
seed | Non | Graine aléatoire ; zéro demande une graine au hasard. |
Tarification
La facturation se fait par blocs entiers de 5 secondes du clip source : un clip de 6 secondes coûte donc autant que 10 secondes. L’estimation affichée avant l’envoi retient la durée réelle d’un clip téléversé, ou le maximum de 30 secondes pour une URL vidéo ; toute différence est libérée au règlement.
| Spécification | Prix |
|---|---|
| $0.064 / seconde |
| $0.12 / seconde |
Cas d’utilisation
Redistribuer un plan qui fonctionne déjà
La prise dont la lumière, les placements et le mouvement de caméra sont validés reste en place : vous changez la tête plutôt que de régénérer tout le plan et de perdre le jeu de l’interprète.
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 plus bas ne change pas non plus : c’est une condition ferme, pas une formalité.
Une même personne sur toute une série générée
Générez une série de plans avec n’importe quel modèle vidéo, analysez chacun d’eux, puis faites passer la même tête consentie dans tous, pour que la série se lise comme une seule personne.
Une foule dont une seule personne change
Analysez une scène à plusieurs personnes, regardez les vignettes et ne renvoyez que la position visée. Toutes les autres restent intactes.
Guide de prompt et conseils pratiques
Vérifiez vos droits sur chaque tête concernée
Le métrage comme les photos de référence montrent des personnes. Il vous faut une autorisation pour l’image que vous déplacez et pour le métrage dans lequel vous la placez. Conservez l’autorisation avec la fiche du travail.
Analysez d’abord, puis lisez l’ordre des vignettes
L’analyse renvoie les vignettes dans un ordre fixe. La première image est object_index 0, la deuxième 1, et ainsi de suite. Cette position est la seule prise dont vous avez besoin : vous la renvoyez dans swap_targets.
Gardez la vidéo et la résolution identiques
Les deux appels doivent porter sur la même vidéo à la même résolution. Omettez video_url au second appel et il est repris de l’analyse ; si vous l’envoyez, il doit correspondre. Une résolution différente est refusée plutôt que resuivie en silence.
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-edit",
"input": {
"analysis_task_id": "example",
"resolution": "720p",
"swap_targets": [
{
"image_urls": [
"example"
],
"object_index": 0
}
]
}
}'
# 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.
