API de face swap: cómo añadir cambio de cara a tu app

Una API de face swap permite que tu app ponga la cara de una persona en otra foto con una sola petición HTTP. Esta guía muestra la petición en curl, JavaScript y Python, cómo gestionar trabajos largos y fotos de grupo, qué significan los errores, cuánto cuesta y cómo usarla de forma responsable.

Equipo de Morfran · 5 min de lectura · actualizado el 22 nov. 2026

Qué hace una API de cambio de cara

Una API de face swap recibe dos imágenes y devuelve una nueva. La imagen de origen muestra la cara que quieres usar. La imagen de destino es la foto que quieres cambiar. La API encuentra la cara en el destino, la sustituye por la cara del origen y ajusta el tono de piel, la luz y el ángulo para que el resultado parezca una sola foto.

Los desarrolladores la usan para cosas como tarjetas de felicitación personalizadas, campañas de «ponte en el póster», herramientas de avatar y perfil, personajes de videojuegos y apps de fotomatón en eventos. En lugar de entrenar y alojar tus propios modelos, envías una petición HTTP y recibes una imagen.

Antes de empezar

Necesitas tres cosas:

  1. Una cuenta de Morfran. Las cuentas nuevas reciben 50 créditos gratis, suficientes para diez cambios de cara individuales.
  2. Una clave API. Créala en tu panel, en Claves API. Guárdala en tu servidor y nunca la pongas en el código del navegador o de una app móvil.
  3. Dos URL públicas de imágenes. JPG, PNG o WebP. El origen debe mostrar una cara clara, mirando más o menos a la cámara.

Cada petición envía la clave en la cabecera X-API-Key. La URL base es https://api.morfran.com.

Tu primer cambio de cara con 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"}'

Por defecto, la llamada es síncrona: la API espera el resultado (hasta unos 60 segundos) y devuelve una respuesta JSON con un enlace a la imagen terminada en cdn.morfran.com, además de los créditos usados. Descarga la imagen enseguida, porque los resultados se borran al cabo de una hora.

La misma petición 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);

Ejecuta esto en tu servidor, no en el navegador, para que tu clave siga siendo privada.

La misma petición 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())

Trabajos largos: usa el modo asíncrono

Si tu app no debe esperar con una petición abierta, añade ?async=true a la URL. La API responde al momento con un id de tarea. Después consulta el resultado con GET /v1/face-swap/{taskId} cada pocos segundos hasta que esté listo. Funciona bien detrás de una cola de trabajos o cuando tu propio servidor tiene un tiempo de espera de petición corto.

Fotos de grupo: cambia hasta ocho caras

Para una foto de equipo o de familia, usa POST /v1/face-swap/group. Cambia hasta ocho caras en una sola llamada; MaxFaces fija el límite. Un cambio de cara en grupo cuesta 10 créditos y uno individual 5 créditos. La lista completa de campos está en la documentación de la API y en el esquema OpenAPI.

Gestiona errores y créditos

  • 401: falta la clave API o es incorrecta. Revisa la cabecera X-API-Key.
  • 402: no hay créditos suficientes. Compra un paquete de créditos en tu panel.
  • 422: no se encontró ninguna cara. Pide al usuario una foto más clara con una sola cara.

Las peticiones fallidas no se cobran. Los créditos solo se descuentan por imágenes terminadas, así que reintentar después de un 422 no cuesta el doble. Puedes consultar tu saldo en cualquier momento con GET /v1/credits/balance, que es gratis.

Consejos para mejores resultados

  • Usa una cara de origen clara. Una sola persona, mirando a la cámara, con los ojos abiertos, sin gafas de sol y con buena luz.
  • Haz coincidir el ángulo. Una cara que mira de frente encaja mejor en un destino donde la persona también mira más o menos a la cámara.
  • Que las caras sean lo bastante grandes. Una cara de solo unos pocos píxeles de ancho en el destino no se puede cambiar bien.
  • Una luz parecida ayuda. Una cara fotografiada con luz de día se ve más natural en una foto de destino con luz de día.
  • Prueba con tus imágenes reales. Gasta algunos de los créditos gratis en fotos como las que subirán tus usuarios.

Consentimiento y privacidad

Cambia solo la cara de alguien que haya dado su permiso. No uses el cambio de cara para engañar, para suplantar a alguien ni para crear contenido que perjudique a una persona real. Si publicas resultados, indica que están generados con IA. Las imágenes subidas y los resultados se borran de nuestro almacenamiento en menos de una hora, y no los usamos para entrenar modelos de IA. Puedes denunciar un mal uso a través de la página de contacto y se gestiona en 48 horas.

Úsala desde un agente de IA

El mismo cambio de cara está disponible en el servidor MCP de Morfran en https://api.morfran.com/mcp, así que asistentes como Claude pueden llamarlo con tu clave API. La configuración se describe en la sección MCP de la documentación.

Preguntas

¿Cuánto cuesta la API de cambio de cara?

Un cambio de cara individual cuesta 5 créditos y un cambio de cara en grupo (hasta ocho caras) cuesta 10 créditos. Las cuentas nuevas reciben 50 créditos gratis. Después compras paquetes de créditos; no hay suscripción. Consulta los paquetes en precios.

¿Cuánto tarda un cambio de cara?

La mayoría de los resultados llegan dentro de la espera síncrona de unos 60 segundos. Para trabajos largos o tiempos de espera de servidor cortos, usa ?async=true y consulta el resultado con el id de tarea.

¿Puedo enviar las imágenes en base64 en lugar de URL?

Los ejemplos de aquí usan URL públicas, que es la forma más sencilla. El esquema OpenAPI enumera todos los campos de entrada que acepta el endpoint.

¿Cuánto tiempo se guardan los resultados?

Las imágenes subidas y los resultados se borran en menos de una hora. Guarda la imagen resultante en tu lado en cuanto la recibas.

¿Puedo probarlo sin escribir código?

Sí. Inicia sesión y abre el Playground. Ejecuta el mismo cambio de cara en el navegador y muestra la petición API correspondiente.