Workflow d'API d'échange de visages par IA : envois autorisés, tâches asynchrones et livraison fiable

Comparer les photos de référence et les couleurs avant l'échange.

Sur SpicyAPI, le Face Swap est une famille d'endpoints sans censure qui reçoivent deux images (ou une image et un clip), sans prompt et sans masque. Ce guide couvre le choix de l'endpoint à appeler, la façon de l'essayer d'abord dans le Playground puis depuis le code ou avec un agent, ce qu'il faut vérifier dans la sortie et comment conserver le résultat après sa suppression par la plateforme.

Choisir l'endpoint adapté à la tâche

Commencez par Face Swap à $0.013. Passez à Pro quand le visage échangé paraît plus lisse ou plus net que le reste du cadre, et à Plus quand les deux photos ont des teints de peau ou des couleurs de lumière nettement différents. 200 variantes d'avatar coûtent $2.60 avec Face Swap et $32 avec Pro, alors testez votre paire la plus difficile sur les deux. Plus possède un champ prompt qui n'a aucun effet, laissez-le donc de côté et mettez plutôt les lunettes ou l'expression dans la photo cible.

Video Face Swap facture le clip source en blocs entiers de 10 secondes : un clip de 12 secondes est facturé comme 20 secondes ($0.52) et un clip de 40 secondes comme $1.04. À l'envoi, l'estimation de 40 secondes ($1.04) est retenue et la différence est libérée lorsque la tâche est facturée. Rognez jusqu'à une limite de bloc avant d'envoyer.

Ce que font les endpoints avec de vrais visages

Ces endpoints sont proposés sans censure : SpicyAPI n'ajoute ni scan de visage par requête ni vérification de personne réelle. Les échecs concernent généralement l'entrée (aucun visage détectable, un fichier injoignable), même si un modèle donné peut refuser une requête. La politique d'utilisation acceptable interdit l'usurpation d'identité, l'usage intime ou sexualisé non autorisé de la ressemblance d'une personne réelle et tout ce qui implique des mineurs ; après un signalement, SpicyAPI peut supprimer les ressources stockées et suspendre l'accès. Une photo publique ou une relation antérieure ne constitue pas un consentement. Le dossier de consentement vous appartient et se place avant le bouton d'envoi :

• L'utilisateur connecté confirme qu'il dispose de l'autorisation de la personne représentée pour les deux images et pour cet usage ; conservez la confirmation avec le projet (qui, quelle ressource, quel usage, quand).
• Aucune image de mineurs et aucun usage qui usurpe une personne réelle pour tromper.

Conservez cela comme des registres de produit, pas dans les prompts, les événements analytiques ou les journaux.

Préparer des entrées qui n'échoueront pas

Il n'y a aucun réglage d'intensité à ajuster, un mauvais résultat signifie donc une autre paire d'entrées.

• Des visages de face, grands et nets. Les forts angles de profil, le flou de mouvement, l'occlusion dense (mains, masques, grandes lunettes de soleil) et les très petits visages dégradent le transfert ou font échouer la requête. Un visage de référence grand, net et de face donne le meilleur résultat.
• La même direction de lumière. L'échange ne rééclaire pas la cible, une référence éclairée du côté opposé apparaît donc comme une couture à la ligne de la mâchoire. Faites correspondre la direction et le teint de peau approximatif, ou choisissez une autre référence. Plus ne fait qu'harmoniser le teint de peau ; il ne corrige pas un écart de direction de lumière.
• Un visage par image. Pour les photos de groupe, Face Swap et Video Face Swap acceptent face_mapping : jusqu'à 10 entrées, chacune associant un visage de référence à un visage cible, numérotés à partir de 0 dans l'ordre de détection. Revérifiez la numérotation chaque fois que vous changez une image. Plus et Pro supposent un seul visage ; recadrez d'abord.

``json "face_mapping": [{ "reference_face_index": 0, "target_face_index": 1 }] ``

Ceci échange le visage de référence 0 sur le deuxième visage trouvé dans la cible. Laissez le champ de côté pour échanger un seul visage.

• Des liens de fichiers directs. Les URL d'image doivent mener au fichier sans connexion. Pour la vidéo, une page qui lit le clip renvoie du HTML, pas un clip, et l'appel échoue avec remboursement des frais ; téléversez plutôt le fichier.
• Les rôles ne sont pas interchangeables. image_url est l'image qui est modifiée ; reference_image_url fournit le visage. Les inverser constitue une requête valide au résultat différent, sans aucune erreur renvoyée : un échange dans le mauvais sens ressemble donc à un bug du modèle.

Limites pour la vidéo : MP4 jusqu'à 90 MB et de 3 à 40 secondes, image de référence JPG, PNG ou WEBP jusqu'à 10 MB. Gardez le visage grand dans le cadre et non tourné longtemps. L'endpoint fonctionne mieux avec une seule personne à l'écran ; pour un clip avec plusieurs personnes, ajoutez face_mapping (même forme que ci-dessus, numérotation dans l'ordre de détection) ou recadrez sur la personne.

Essayez d'abord dans le Playground

Ouvrez la page de tâche Face Swap et utilisez l'onglet Playground (configurer, estimer, exécuter). Saisissez l'image cible et l'image du visage de référence, vérifiez l'estimation de prix pour vos réglages, puis lancez l'exécution. Testez ici votre paire la plus difficile avant d'écrire du code : si le résultat est incorrect dans le Playground, il le sera aussi via l'API, et la correction passe par une autre paire d'entrées. Head Swap propose le même onglet pour les échanges de tête entière.

Appelez-le ensuite depuis le code

Installez le SDK Python (pip install spicyapi), définissez SPICY_API_KEY dans l'environnement et exécutez :

import json
import uuid
from pathlib import Path
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
job_file = Path("avatar-8841-layout-02-v1.json")  # keep this file to resume this job

if job_file.exists():
    job = json.loads(job_file.read_text())
else:
    target = client.upload_file("./layout-02.png")
    face = client.upload_file("./approved-portrait.png")
    job = {
        "key": str(uuid.uuid4()),
        "input": {"image_url": target["uri"], "reference_image_url": face["uri"],
                  "style": "realistic", "seed": 4242},
    }
    job_file.write_text(json.dumps(job))  # persist the exact key and payload BEFORE submit

if "taskId" not in job:
    task = client.create_task(
        model="spicyapi/face-swap-v1/edit", input_data=job["input"],
        idempotency_key=job["key"],
    )
    job["taskId"] = task["taskId"]
    job_file.write_text(json.dumps(job))

print("Resume task:", job["taskId"], flush=True)
final = client.wait_for_terminal(job["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {job['taskId']} ended as {final['state']}")
assets = output_assets(final)
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 {job['taskId']} has no ready output; check this task, not a new run")
print(assets[0]["url"])  # copy it to your own storage now

Exécutez un processus par fichier de tâche. Si l'attente expire, relancez avec le même fichier pour reprendre la tâche enregistrée. Si c'est l'envoi lui-même qui a expiré avant de renvoyer un ID, conservez le fichier et rapprochez cette requête avant de réessayer ; la protection d'idempotence n'est pas permanente. N'utilisez un nouveau nom de fichier de tâche que lorsque vous voulez une nouvelle requête payante.

Les téléversements, l'attente, les erreurs et les reprises figurent dans le guide du Subject Swap et dans la référence du SDK Python. Video Face Swap utilise spicyapi/face-swap-video-v1/video-edit avec video_url et reference_image_url.

Ou laissez un agent exécuter le travail

Si un assistant doit effectuer les échanges à votre place, donnez-lui la CLI ou le serveur MCP. Les deux affichent le prix et vous demandent une confirmation avant un appel payant. Le Skill ajoute des instructions par-dessus l'un ou l'autre.

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

``bash spicyapi files upload ./layout-02.png # prints a spicy:// URI SWAP_REQUEST_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')" printf 'Save this request key: %s\n' "$SWAP_REQUEST_KEY" spicyapi tasks create --model spicyapi/face-swap-v1/edit \ --input-file input.json --idempotency-key "$SWAP_REQUEST_KEY" --wait ``

input.json contient le même objet input que ci-dessus, avec les URI spicy://. Ce bloc démarre une nouvelle tâche. Conservez la clé et l'ID de tâche qu'il affiche ; après un délai dépassé, reprenez cette tâche au lieu de relancer le bloc avec une nouvelle clé.

• Serveur MCP. Ajoutez le serveur MCP à votre assistant, puis demandez : "Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap." Il appelle spicyapi_upload_file, puis spicyapi_task_create (qui s'arrête pour votre confirmation de prix), puis spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill installe l'Agent Skill, qui apprend à un assistant de code à lire le schéma en direct, à réutiliser les clés d'idempotence et à enregistrer les résultats au lieu de deviner. Il ne peut pas exécuter de tâches tout seul, utilisez-le donc avec la CLI ou MCP.

Le dossier de consentement et la copie des résultats dans votre propre stockage s'appliquent aux appels d'un agent exactement comme aux vôtres.

Vérifiez avant de conclure

succeeded signifie que la génération est terminée. Avant le téléchargement, vérifiez que la ressource a une URL exploitable et que ni pending ni unavailable n'est vrai ; tant que pending est vrai ou que l'URL manque, continuez d'interroger la même tâche. La disponibilité pour la livraison ne signifie pas non plus que l'image est approuvée. Pour la vidéo, examinez les coupes et les mouvements rapides, pas seulement la première image. Un score de similarité est un signal de diagnostic, ni un consentement ni une autorisation de publication.

Deux vérifications qui changent ce que vous ferez ensuite :

• Les cheveux font partie du design (un personnage de jeu, une mascotte). Face Swap conserve la coiffure de la cible, le nouveau visage se retrouve donc sous les cheveux anciens. Utilisez plutôt Head Swap, avec une image fixe de la fiche personnage comme référence, et comparez chaque sortie à la fiche : un visage qui dérive sur une composition stable est un problème d'identité, l'inverse est un problème de cadrage, et une reprise n'en corrige qu'un seul.
• Un portrait sur plusieurs mises en page. Exécutez Face Swap une fois par mise en page avec la même référence et le même seed. Acceptez une sortie lorsque le visage reste reconnaissable par rapport au portrait au format de recadrage que vous publiez, lorsque les lunettes et la racine des cheveux n'ont pas dérivé et qu'aucune personne supplémentaire n'apparaît ; conservez la révision de référence, la révision de la cible et l'ID de tâche avec elle.

Livrer : copiez le résultat vous-même

Les sources téléversées sont supprimées après un jour et les résultats après 14 jours au maximum (retention.outputsExpireAt contient l'heure exacte). Téléchargez le résultat et conservez-le vous-même ; le lien du résultat dure environ 20 minutes. Voir le guide de conservation.

Quand ça ne marche pas

FAQ

L'API refusera-t-elle le visage d'une personne réelle ?

SpicyAPI ne vérifie pas : il n'y a ni contrôle de personne réelle ni scan par requête, et les échecs concernent généralement l'entrée. Un modèle donné peut tout de même refuser, et la politique d'utilisation acceptable interdit l'usurpation d'identité, l'usage intime non autorisé et les mineurs. Construisez vous-même le dossier d'autorisation.

Puis-je envoyer une vidéo et une image en un seul appel ?

Oui, avec Video Face Swap : un MP4 et une photo de référence. Pour plusieurs personnes dans un clip, utilisez face_mapping à cet endroit, ou le flux Video Head Swap en deux étapes quand vous avez besoin de têtes entières.

API hébergée ou échange open source auto-hébergé ?

L'endpoint hébergé coûte $0.013 par image et vous épargne la mise à disposition de GPU et la maintenance des modèles. L'auto-hébergement remplace les frais par image par des coûts de GPU et d'exploitation ; le fait que ce soit moins cher dépend du débit et du taux d'utilisation. Un volume élevé et constant peut répartir ces coûts sur plus d'images, mais vous devez toujours maintenir les contrôles de consentement et de conservation.

Est-ce la même chose qu'une API générale d'édition d'images ?

Non. Un endpoint d'échange reçoit deux images (ou une image et un clip), sans prompt et sans masque, et chaque endpoint décide ce qui est conservé de la cible : Face Swap conserve les cheveux, Head Swap les remplace. La même paire d'entrées peut échouer à la revue différemment selon l'un ou l'autre, choisissez donc d'abord l'endpoint.

Dois-je conserver les portraits d'origine avec le résultat ?

Seulement si vous avez une raison claire et une politique de conservation déclarée. Les sources téléversées sur SpicyAPI sont de toute façon supprimées au bout d'un jour, alors conservez plutôt les ID de révision de référence et de cible ainsi que l'ID de tâche comme traçabilité, au lieu d'une copie permanente de chaque portrait.

Ai-je besoin de webhooks ou l'interrogation suffit-elle ?

L'interrogation seule fonctionne et constitue le chemin de récupération : lisez toutes les quelques secondes, ou ajoutez wait (jusqu'à 60 s) à createTask pour les échanges d'images courts. Ajoutez un webhook pour une latence plus faible, enregistrez chaque événement une seule fois et traitez l'interrogation comme le rapprochement des callbacks manqués.

Ce que vous devez savoir répondre

Une fonction d'échange de visages gagne la confiance quand votre équipe peut dire quelles images ont été utilisées, quelles révisions sont entrées, si la tâche a été acceptée une seule fois, pourquoi un résultat a été livré et comment il est supprimé. Les dossiers de consentement, les clés d'idempotence, votre propre stockage et une étape de revue sont ce qui produit ces réponses.