API Video Head Swap : analyse, choix de la cible et montage

Video Head Swap est un flux API en deux étapes : analysez un MP4 de 5 à 30 secondes, regardez les aperçus de têtes numérotés, puis envoyez la position choisie et les portraits de remplacement au montage. Le visage, la coiffure, la couleur des cheveux et la forme de la tête changent ; le corps, la tenue, les mouvements, l'audio et toutes les personnes que vous ne sélectionnez pas restent tels qu'ils ont été tournés.

Ici vous voyez d'abord chaque tête détectée et vous nommez celle que vous voulez, avant de payer le montage. Il monte une vidéo existante ; il n'anime pas deux photos fixes pour en faire une performance (utilisez un modèle image vers vidéo pour cela).

Choisir le bon échange

L'échange de visage est le choix le moins cher et le plus simple dès que les cheveux du clip peuvent rester. L'échange de tête est rentable quand les nouveaux cheveux font partie du personnage, au prix d'une jonction au niveau du cou que vous devez inspecter.

Préparer la source et les portraits de référence

N'utilisez que des images de personnes que vous êtes autorisé à traiter : la vôtre, celle d'un interprète avec une autorisation signée, ou une tête générée. Toutes les personnes visibles doivent être adultes. Les deux appels sont sans censure, donc SpicyAPI n'ajoute aucun filtre de contenu et cette vérification vous revient.

Dans cet exemple, un adulte fictif en veste couleur rouille se tourne vers un autre adulte pendant une conversation de douze secondes. Ne remplacez que la tête de la première personne ; gardez la seconde personne, les vêtements et le dialogue.

Exportez la source finale avant l'analyse : MP4, jusqu'à 90 Mo, de 5 à 30 secondes. video_url accepte un lien HTTPS public qui renvoie le MP4 lui-même, pas une page de lecteur HTML, ou une URI spicy:// du flux de téléversement gratuit, qui est la voie la plus fiable pour un fichier local. Si vous rognez, recadrez ou réencodez la source plus tard, relancez l'analyse.

Préparez 1 à 3 portraits du même adulte de remplacement. Une vue de face et une vue trois quarts constituent une bonne paire de départ ; ajoutez un profil si la source contient une rotation importante de la tête. Gardez la coiffure et l'âge apparent cohérents sur toute la série. Faites correspondre les portraits au clip également : éclairez-les depuis la direction d'éclairage du plan, avec la tête dans un angle similaire. La jonction au niveau du cou est là où une discordance se voit, et aucun champ de la requête ne la compense. Les références de tenue en pied appartiennent au remplacement de personnage ; cette tâche exige que la tête et les cheveux visés soient clairement visibles.

Pour une image de référence fictive, utilisez un brief comme celui-ci :

Portrait photographique de référence d'un homme adulte fictif, environ 35 ans, cheveux courts foncés, barbe taillée et expression neutre, portant une chemise simple entièrement boutonnée. Lumière douce et uniforme, visage et cheveux dégagés, fond simple. Vue de face, aucune autre personne, aucun texte.

Créez les autres angles à partir de cette identité approuvée plutôt que de demander des personnes sans lien les unes avec les autres. Le montage n'a pas de champ prompt, donc les références portent tout le résultat.

Illustration d'un jeu de références de face, en trois quarts et de profil.

Essayez d'abord dans le Playground

1. Ouvrez la page de montage de Video Head Swap et restez sur l'onglet Playground, en vue Form. Connectez-vous avec un compte approvisionné pour lancer l'exécution.
2. Étape 1, Find the people in your clip. Ajoutez le clip sous Input video (déposez le MP4 ou utilisez Asset URL) et choisissez Resolution, 480p ou 720p. Le montage doit utiliser la même valeur, donc choisissez celle que vous voulez pour le clip final. Appuyez sur Find people in this clip ($0.08).
3. Étape 2, Choose who to replace. Chaque tête détectée apparaît comme un aperçu numéroté. Choisissez celle que vous voulez et ajoutez une à trois photos de référence de l'adulte de remplacement. Ne définissez un Seed que si vous voulez comparer les jeux de références à égalité ; sinon, omettez-le.
4. Lancez le montage, puis vérifiez la mâchoire, le cou, les cheveux et le col du vêtement dans le résultat, avec le son.

L'analyse reste réutilisable pendant 24 heures : vous pouvez donc essayer un autre jeu de références à partir des mêmes aperçus sans payer à nouveau le suivi. Chaque montage accepté, y compris avec un nouveau jeu de références ou une nouvelle seed, est une nouvelle tâche payante. Si aucun aperçu ne montre la personne que vous voulez, un plan plus clair est la solution : une tête jamais clairement visible ne peut pas être suivie, et un clip sans aucune tête traçable échoue avec la retenue libérée.

La page d'analyse exécute l'étape 1 à elle seule ; une analyse réussie est facturée même si vous vous arrêtez là.

Puis exécutez-le en code

Installez le SDK Python (pip install spicyapi), définissez SPICY_API_KEY dans votre environnement et enregistrez ceci sous swap.py. analyze affiche les URL des aperçus ; edit prend l'identifiant de tâche de l'analyse et la position d'aperçu que vous avez choisie. Le montage doit utiliser la même clé d'API et la même résolution que l'analyse, et aucun video_url : il hérite du clip analysé.

import sys
import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

def run(model: str, input_data: dict) -> tuple[str, list]:
    task = client.create_task(model=model, input_data=input_data,
                              idempotency_key=str(uuid.uuid4()))
    final = client.wait_for_terminal(task["taskId"])
    if final["state"] != "succeeded":
        raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
    return task["taskId"], output_assets(final)

if sys.argv[1] == "analyze":
    task_id, previews = run("spicyapi/head-swap-video-v1/video-analyze", {
        "video_url": "https://your-media.example/conversation.mp4",
        "resolution": "720p",
    })
    print("analysis task:", task_id)
    for position, asset in enumerate(previews):   # position 0 is the first image returned
        print(position, asset["url"])
else:  # python swap.py edit <analysis_task_id> <position>
    _, outputs = run("spicyapi/head-swap-video-v1/video-edit", {
        "analysis_task_id": sys.argv[2],
        "resolution": "720p",
        "swap_targets": [{
            "object_index": int(sys.argv[3]),
            "image_urls": [
                "https://your-media.example/replacement-front.png",
                "https://your-media.example/replacement-three-quarter.png",
            ],
        }],
        "seed": 42,
    })
    print(outputs[0]["url"])  # copy the video to your own storage now

Lancez python swap.py analyze, ouvrez chaque aperçu et notez le numéro de l'adulte que vous voulez (la position 0 est la première image renvoyée, ce n'est pas une règle de gauche à droite ; ne retombez jamais sur 0 si votre personne est absente), puis python swap.py edit <analysis_task_id> 1. Le montage accepte de 1 à 10 cibles avec 1 à 3 images de référence de la même personne chacune ; il n'y a pas d'entrée de masque, de tenue, d'audio ni de prompt. La création, l'attente, les nouvelles tentatives, les clés d'idempotence et les téléchargements sont couverts dans le guide des tâches et la référence du SDK Python ; un fichier local passe par le flux de téléversement gratuit et revient sous forme d'URI spicy:// pour video_url.

Ou laissez un agent l'exécuter

Quand un assistant doit exécuter les deux appels, les trois outils officiels affichent le prix et vous demandent avant un appel payant.

• CLI. Placez l'objet input de l'analyse (video_url, resolution) dans analysis.json, puis :

``bash spicyapi tasks create --model spicyapi/head-swap-video-v1/video-analyze --input-file analysis.json --wait ``

Lancez le montage de la même façon avec edit.json. Voir la documentation de la CLI ; npx @spicyapi/cli fonctionne sans installation.

• Serveur MCP. Ajoutez le serveur MCP, puis demandez : "Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." Il téléverse le fichier avec spicyapi_upload_file, appelle spicyapi_task_create, qui s'arrête pour votre confirmation du prix, puis spicyapi_task_wait. Choisissez la position vous-même, puis demandez le montage.
• Skill. npx skills add spicyapi-ai/spicy-skill installe l'Agent Skill, qui fait qu'un assistant de code lit le schéma du modèle en direct au lieu de deviner les champs.

À quoi ressemble un montage terminé

L'exemple de modèle publié ci-dessous est un clip source de dix secondes et son montage en 480p avec un portrait de référence. Les cheveux et le visage changent ; la robe, la démarche, le contre-jour et la caméra restent. Vérifiez d'abord la mâchoire et la ligne du cou, là où une discordance de lumière ou d'angle se voit.

Ce que cela coûte

Le montage coûte $0.064 par seconde facturée en 480p et $0.12 en 720p. La facturation se fait par blocs de cinq secondes, avec un minimum de cinq secondes et un plafond de trente secondes. Un clip de 10 secondes en 480p coûte $0.72 au total : $0.08 d'analyse plus $0.64 de montage.

Avant le règlement, le montage réserve le maximum de trente secondes, $1.92 en 480p ou $3.60 en 720p. Un clip de douze secondes en 720p est retenu à $3.60 bien que son montage soit facturé $1.80 ; le reste est libéré lorsque la tâche est réglée.

Diagnostiquer séparément la sélection, l'identité et la livraison

Illustration de l'examen des cheveux, du col et d'une main au premier plan.

Regardez la vidéo renvoyée avec le son. Le montage conserve l'audio et les mouvements du corps de la source ; il ne change pas la voix de la personne qui parle, et le décor n'est pas garanti identique au pixel près. Inspectez aussi la personne non sélectionnée, en particulier lors des croisements. Si une main traverse le visage remplacé, parcourez le contact et la réapparition image par image au lieu d'approuver uniquement une première image séduisante.

Enregistrez immédiatement la vidéo acceptée dans votre propre stockage : les liens de résultat durent environ 20 minutes et les résultats sont conservés au maximum 14 jours ; un identifiant d'analyse, une image d'aperçu et une URL média temporaire ne sont donc pas une copie permanente.