Video Character Swap : références, choix de la cible et vérification

Utilisez Character Swap quand le remplacement doit changer l'apparence complète d'une personne, y compris sa carrure et ses vêtements, tandis que la scène, le mouvement de caméra et le son original restent inchangés. Character Swap vous permet de choisir quelle personne du clip est remplacée : analysez le clip final, inspectez les prévisualisations numérotées, puis envoyez l'index de prévisualisation choisi avec une à trois images de la personne de remplacement. Si la tenue d'origine doit rester, utilisez plutôt un workflow head swap ou face swap.

Sur SpicyAPI, l'analyse et l'édition sont deux tâches payantes distinctes. Une source de sept secondes coûte au total $0.72 en 480p ou $1.28 en 720p : une analyse plus l'édition, qui arrondit à dix secondes. Le Playground exécute les deux étapes dans le navigateur, et l'API accepte les mêmes entrées. Vous avez besoin d'une autorisation pour le footage comme pour la ressemblance dans les images de référence.

Préparer une scène de sept secondes et un remplacement en pied

Notre exemple est un plan de sept secondes de quelqu'un qui porte une caisse à outils fermée jusqu'à un établi, tandis qu'un autre adulte se tient à côté. La personne qui porte est remplacée par une adulte fictive en veste de travail bleu marine et pantalon gris charbon, l'apparence des illustrations ci-dessous. L'établi, la caisse à outils, l'autre personne et la performance d'origine restent.

Exportez exactement la source de sept secondes que vous comptez modifier. Conservez la prise initiale, l'action de port et le relâchement une fois la caisse à outils arrivée sur l'établi. L'entrée est une MP4 de 5 à 30 secondes jusqu'à 90 MB. Téléverser le fichier est la voie la plus fiable ; un lien direct doit pointer vers le fichier MP4 lui-même, car une page contenant un lecteur échoue (le montant facturé est remboursé). Rogner ou réencoder après l'analyse exige une nouvelle analyse.

Le tracker suit les personnes qui restent assez grandes et visibles, donc coupez sur le passage qui compte et évitez les longues périodes où la personne visée est complètement cachée. Un cut plus court coûte aussi moins cher, car l'édition est facturée par blocs de cinq secondes.

Pour le remplacement, préparez une vue en pied de face et une vue trois quarts de la même adulte, avec la même tenue. Une référence claire est acceptée ; trois est le maximum par cible. Un portrait tête-épaules laisse la carrure et les vêtements à l'approximation, alors montrez les manches, les mains et les chaussures, et éclairez les références comme le footage plutôt que de choisir le portrait le plus net. Ne combinez pas le visage d'une personne, le pantalon d'une autre et une veste différente sur la troisième image. Le service reçoit cela comme des références pour un remplacement, pas comme des couches de vêtements attribuées séparément.

Un brief exploitable pour générer l'image est :

Portrait de référence en pied d'une femme adulte fictive, environ 30 ans, en veste de travail bleu marine unie, pantalon gris charbon et chaussures plates sombres. Pose détendue de face, mains visibles, manches et chaussures lisibles, fond neutre. Pas de caisse à outils, pas d'autres personnes, pas de lettrage.

Générez ou photographiez un second angle du même design établi si nécessaire. L'édition character swap n'a pas de champ de prompt texte, pas de sélecteur de tenue ni de masque corporel, donc la tenue voulue doit figurer dans les images de référence.

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

Essayez d'abord dans le Playground

1. Ouvrez la page du modèle Video Character Swap et restez sur l'onglet Playground en vue Form. Connectez-vous avec un compte approvisionné pour lancer.
2. Dans Step 1, Find the people in your clip, ajoutez la MP4 de sept secondes sous Input video (téléverser est plus fiable qu'un lien) et choisissez la Resolution voulue pour le clip final, 480p ou 720p. L'édition doit utiliser la même valeur.
3. Appuyez sur Find people in this clip ($0.08). Toutes les personnes détectées apparaissent dans Step 2, Choose who to replace, une prévisualisation recadrée par personne.
4. Choisissez la prévisualisation de la personne qui porte la caisse à outils, ajoutez une à trois images de référence du remplacement et lancez l'édition. Une Seed est facultative.

La position 0 est la première prévisualisation renvoyée, pas nécessairement la personne la plus à gauche ou la plus grande, car l'ordre vient du suivi et non de la position à l'écran. Si la personne qui porte est la deuxième prévisualisation, c'est l'index 1. Gardez l'ordre renvoyé quand vous enregistrez les prévisualisations : des noms de fichiers alphabétiques ou une galerie triée peuvent changer silencieusement l'index.

Si la personne visée n'a pas de prévisualisation, ne payez pas une édition en devinant un numéro voisin. Aucune image de référence ne peut faire revenir une personne sans prévisualisation, utilisez donc un plan où cette personne est clairement visible. Une analyse qui ne trouve personne se termine en échec et sa réservation est libérée ; une analyse réussie est facturée même si vous décidez de ne pas faire le swap.

Puis appelez-la depuis le code

Installez le SDK Python (pip install spicyapi), définissez SPICY_API_KEY et exécutez ce qui suit. Cela téléverse le clip et deux références, lance l'analyse, affiche les liens de prévisualisation, demande quel index remplacer, puis soumet l'édition. Les deux tâches sont facturées.

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
RESOLUTION = "720p"     # must be identical in both calls

clip = client.upload_file("./workshop-seven-seconds.mp4")
front = client.upload_file("./replacement-front.png")
angled = client.upload_file("./replacement-three-quarter.png")

analysis_task = client.create_task(
    model="spicyapi/character-swap-v1/video-analyze",
    input_data={"video_url": clip["uri"], "resolution": RESOLUTION},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume analysis:", analysis_task["taskId"], flush=True)
analysis = client.wait_for_terminal(analysis_task["taskId"])
if analysis["state"] != "succeeded":
    raise RuntimeError(f"Analysis {analysis_task['taskId']} ended as {analysis['state']}")

previews = output_assets(analysis)
if not previews or any(p.get("pending") or p.get("unavailable") or not p.get("url") for p in previews):
    raise RuntimeError(f"Analysis {analysis_task['taskId']} has no ready previews; retrieve it before editing")
for index, preview in enumerate(previews):  # keep the returned order
    print(index, preview["url"])
chosen = int(input("Index of the person to replace: "))
if not 0 <= chosen < len(previews):
    raise ValueError("Choose one of the returned preview indices before creating an edit")

edit_task = client.create_task(
    model="spicyapi/character-swap-v1/video-edit",
    input_data={
        "analysis_task_id": analysis["taskId"],  # video_url is inherited from the analysis
        "resolution": RESOLUTION,
        "swap_targets": [{"object_index": chosen,
                          "image_urls": [front["uri"], angled["uri"]]}],
        "seed": 42,
    },
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume edit:", edit_task["taskId"], flush=True)
edit = client.wait_for_terminal(edit_task["taskId"])
if edit["state"] != "succeeded":
    raise RuntimeError(f"Edit {edit_task['taskId']} ended as {edit['state']}")
assets = output_assets(edit)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {edit_task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy it to your own storage now

Les téléversements, l'attente, les erreurs et les reprises sont couverts dans le guide subject swap, la documentation des tâches et la référence du SDK Python. Utilisez la même clé API pour les deux étapes et lancez l'édition dans les 24 heures suivant l'analyse (un clip téléversé expire aussi après un jour) ; une analyse peut alimenter plusieurs éditions facturées séparément. Les personnes que vous ne listez pas restent intactes, et un index appartient à cette analyse : ne le réutilisez donc pas comme identifiant de personnage dans un autre plan.

L'intention d'un remplacement de personnage entier est de conserver la scène, le mouvement de caméra, la chorégraphie et le son original. Ce périmètre ne promet pas des pixels d'arrière-plan inchangés ni une nouvelle voix.

Ou laissez un agent l'exécuter

Si un assistant doit effectuer le swap, donnez-lui la CLI ou le serveur MCP. Les deux affichent le prix et vous demandent de confirmer avant un appel payant. La Skill ajoute des instructions par-dessus l'un ou l'autre.

• CLI. spicyapi exécute une tâche depuis un terminal (npx @spicyapi/cli fonctionne sans installation) :

``bash spicyapi files upload ./workshop-seven-seconds.mp4 # prints a spicy:// URI spicyapi tasks create --model spicyapi/character-swap-v1/video-analyze \ --input-file analysis.json --idempotency-key workshop-analysis-v1 --wait ``

analysis.json contient {"video_url": "spicy://...", "resolution": "720p"}. Regardez les prévisualisations, puis lancez la commande avec video-edit, sa propre clé workshop-edit-v1 et un input.json contenant analysis_task_id, resolution et swap_targets. Ne réutilisez une clé que pour une requête inchangée ; une nouvelle source, une nouvelle cible ou un nouveau jeu de références exige une nouvelle clé.

• Serveur MCP. Ajoutez le serveur MCP (son extrait de configuration est sur cette page) à votre assistant, puis demandez : "Analyse ./workshop-seven-seconds.mp4 en 720p avec Character Swap et montre-moi les prévisualisations." Après avoir choisi la personne, dites : "Remplace l'index 1 avec ./replacement-front.png et ./replacement-three-quarter.png." Il appelle spicyapi_upload_file, puis spicyapi_task_create (qui s'arrête pour votre confirmation de prix), puis spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installe l'Agent Skill, qui apprend à un assistant de code à lire le schéma en direct et à réutiliser les clés d'idempotence. Il ne peut pas lancer de tâches tout seul, utilisez-le donc avec la CLI ou MCP. Le choix de la prévisualisation à remplacer reste votre décision.

Comprendre le coût avant de faire des variantes

Les prix proviennent du catalogue public (octobre 2026).

La durée d'édition est arrondie à des blocs entiers de cinq secondes, avec un minimum de cinq secondes et un plafond de trente secondes. Une source de 5 secondes utilise un bloc ; 5,1 secondes en utilisent deux. Avant la soumission, l'estimation d'édition réserve le maximum de trente secondes, $1.92 en 480p ou $3.60 en 720p, et la différence est restituée lorsque la tâche est réglée. Un contrôle de budget doit donc autoriser la réservation, pas seulement le montant final attendu. Une requête rejetée à la création (résolution différente, mauvais ID d'analyse, index répété) ne crée ni ne facture rien.

Deux éditions en 720p de la source de sept secondes, en réutilisant une analyse, coûtent $2.48 au total : $0.08 plus deux fois $1.20. Changer les références ou la seed est une nouvelle édition payante, pas une révision gratuite.

Réparer le bon problème

Illustration de la vérification d'une image imprimée.

Regardez ensemble la personne qui porte, la caisse à outils et l'adulte non sélectionné à vitesse normale. Inspectez ensuite la prise, le contact avec l'établi et le relâchement. Un nouveau visage peut sembler excellent alors que l'action centrale échoue. Si seule la dernière demi-seconde présente un défaut, un rognage peut suffire ; si la prise est cassée d'un bout à l'autre, choisissez une source plus claire ou utilisez un périmètre de remplacement de tête plus étroit quand le corps et les vêtements d'origine peuvent rester.

Copiez le clip accepté dans votre propre stockage avant qu'il n'expire : les résultats sont conservés environ 14 jours (voir rétention et livraison des médias).