API d'échange de visage : ajoutez le face swap à votre app

Une API de face swap permet à votre app d'insérer le visage d'une personne dans une autre photo avec une seule requête HTTP. Ce guide montre la requête en curl, JavaScript et Python, comment gérer les tâches longues et les photos de groupe, ce que signifient les erreurs, combien cela coûte et comment l'utiliser de façon responsable.

L'équipe Morfran · 5 min de lecture · mis à jour le 22 nov. 2026

Ce que fait une API d'échange de visage

Une API de face swap prend deux images et en renvoie une nouvelle. L'image source montre le visage que vous voulez utiliser. L'image cible est la photo que vous voulez modifier. L'API trouve le visage dans la cible, le remplace par le visage de la source et harmonise le teint, la lumière et l'angle pour que le résultat ressemble à une seule photo.

Les développeurs l'utilisent par exemple pour des cartes de vœux personnalisées, des campagnes du type « mettez-vous sur l'affiche », des outils d'avatar et de profil, des personnages de jeu et des applications de photobooth lors d'événements. Au lieu d'entraîner et d'héberger vos propres modèles, vous envoyez une requête HTTP et recevez une image.

Avant de commencer

Il vous faut trois choses :

  1. Un compte Morfran. Les nouveaux comptes reçoivent 50 crédits gratuits, de quoi faire dix échanges de visage simples.
  2. Une clé API. Créez-la dans votre tableau de bord, rubrique Clés API. Gardez-la sur votre serveur et ne la mettez jamais dans le code d'un navigateur ou d'une application mobile.
  3. Deux URL d'images publiques. JPG, PNG ou WebP. La source doit montrer un visage net, tourné à peu près vers l'objectif.

Chaque requête envoie la clé dans l'en-tête X-API-Key. L'URL de base est https://api.morfran.com.

Votre premier échange de visage avec curl

curl -X POST https://api.morfran.com/v1/face-swap \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"SourceImageUrl":"https://example.com/face.jpg","TargetImageUrl":"https://example.com/photo.jpg"}'

Par défaut, l'appel est synchrone : l'API attend le résultat (jusqu'à environ 60 secondes) et renvoie une réponse JSON avec un lien vers l'image terminée sur cdn.morfran.com, ainsi que les crédits utilisés. Téléchargez l'image tout de suite, car les résultats sont supprimés au bout d'une heure.

La même requête en JavaScript (Node.js)

const res = await fetch("https://api.morfran.com/v1/face-swap", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.MORFRAN_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    SourceImageUrl: "https://example.com/face.jpg",
    TargetImageUrl: "https://example.com/photo.jpg",
  }),
});
const data = await res.json();
console.log(res.status, data);

Exécutez ce code sur votre serveur, pas dans le navigateur, pour que votre clé reste privée.

La même requête en Python

import os
import requests

res = requests.post(
    "https://api.morfran.com/v1/face-swap",
    headers={"X-API-Key": os.environ["MORFRAN_KEY"]},
    json={
        "SourceImageUrl": "https://example.com/face.jpg",
        "TargetImageUrl": "https://example.com/photo.jpg",
    },
    timeout=90,
)
print(res.status_code, res.json())

Tâches longues : utilisez le mode asynchrone

Si votre app ne doit pas attendre sur une requête ouverte, ajoutez ?async=true à l'URL. L'API répond immédiatement avec un identifiant de tâche. Lisez ensuite le résultat avec GET /v1/face-swap/{taskId} toutes les quelques secondes jusqu'à ce qu'il soit prêt. Cela fonctionne bien derrière une file de tâches, ou quand votre propre serveur a un délai de requête court.

Photos de groupe : échangez jusqu'à huit visages

Pour une photo d'équipe ou de famille, utilisez POST /v1/face-swap/group. Il modifie jusqu'à huit visages en un seul appel ; MaxFaces fixe la limite. Un échange de groupe coûte 10 crédits, un échange simple 5 crédits. La liste complète des champs se trouve dans la documentation de l'API et le schéma OpenAPI.

Gérer les erreurs et les crédits

  • 401 : la clé API est absente ou incorrecte. Vérifiez l'en-tête X-API-Key.
  • 402 : crédits insuffisants. Achetez un pack de crédits dans votre tableau de bord.
  • 422 : aucun visage n'a été trouvé. Demandez à l'utilisateur une photo plus nette avec un seul visage.

Les requêtes échouées ne sont pas facturées. Les crédits ne sont prélevés que pour les images terminées, donc une nouvelle tentative après une 422 ne coûte pas deux fois. Vous pouvez consulter votre solde à tout moment avec GET /v1/credits/balance, qui est gratuit.

Conseils pour de meilleurs résultats

  • Utilisez un visage source net. Une seule personne, face à l'objectif, yeux ouverts, sans lunettes de soleil, bonne lumière.
  • Accordez les angles. Un visage qui regarde droit devant se fond le mieux dans une cible où la personne regarde aussi à peu près l'objectif.
  • Gardez des visages assez grands. Un visage qui ne fait que quelques pixels de large dans la cible ne peut pas être bien échangé.
  • Une lumière similaire aide. Un visage photographié à la lumière du jour paraît le plus naturel dans une photo cible prise en lumière du jour.
  • Testez avec vos vraies images. Utilisez quelques crédits gratuits sur des photos semblables à celles que vos utilisateurs enverront.

Consentement et confidentialité

N'échangez que le visage d'une personne qui l'a accepté. N'utilisez pas le face swap pour tromper, pour usurper l'identité de quelqu'un ou pour créer du contenu qui nuit à une personne réelle. Si vous publiez des résultats, indiquez qu'ils sont générés par IA. Les images envoyées et les résultats sont supprimés de notre stockage dans un délai d'une heure, et nous ne les utilisons pas pour entraîner des modèles d'IA. Les abus peuvent être signalés via la page de contact et sont traités sous 48 heures.

L'utiliser depuis un agent IA

Le même échange de visage est disponible sur le serveur MCP de Morfran à l'adresse https://api.morfran.com/mcp, pour que des assistants comme Claude puissent l'appeler avec votre clé API. La configuration est décrite dans la section MCP de la documentation.

Questions

Combien coûte l'API d'échange de visage ?

Un échange de visage simple coûte 5 crédits et un échange de groupe (jusqu'à huit visages) 10 crédits. Les nouveaux comptes reçoivent 50 crédits gratuits. Ensuite, vous achetez des packs de crédits ; il n'y a pas d'abonnement. Voir les tarifs pour les packs.

Combien de temps prend un échange de visage ?

La plupart des résultats arrivent pendant l'attente synchrone d'environ 60 secondes. Pour les tâches longues ou les délais serveur courts, utilisez ?async=true et lisez le résultat avec l'identifiant de tâche.

Puis-je envoyer les images en base64 au lieu d'URL ?

Les exemples ici utilisent des URL publiques, c'est la méthode la plus simple. Le schéma OpenAPI liste tous les champs d'entrée acceptés par l'endpoint.

Combien de temps les résultats sont-ils conservés ?

Les images envoyées et les résultats sont supprimés dans un délai d'une heure. Enregistrez l'image résultat de votre côté dès que vous la recevez.

Puis-je l'essayer sans écrire de code ?

Oui. Connectez-vous et ouvrez le Playground. Il exécute le même échange de visage dans le navigateur et affiche la requête API correspondante.