Introducción
Traslada un rostro de una imagen a la persona de otra y, como parte del traslado, iguala el tono de piel entre ambas. Cuánto se traslada lo decide el motor: funde solo el rostro o la cabeza entera, lo que resulte más natural para ese par, así que el nacimiento del pelo no siempre queda intacto. La pose, la ropa, la luz y el fondo del destino quedan como estaban.
Face Swap Plus es el nivel configurable de la línea Face Swap. Además de las dos imágenes, acepta una instrucción breve por escrito, un formato de archivo de salida y un seed, y se envía a spicyapi/face-swap-v1-plus/edit. La llamada es asíncrona: devuelve un id de tarea, consultas esa tarea y cada solicitud devuelve una imagen, que se factura por imagen de salida sea cual sea el formato pedido.
Funciones y aspectos destacados
El tono de piel se iguala por ti
Donde más a menudo se delata un traslado de rostro es en el borde: una referencia tomada con luz cálida metida en un destino con luz fría deja un halo alrededor de la mandíbula y un cuello que ya no pertenece a la cabeza. Este motor iguala el tono entre las dos fotos durante el traslado, así que un par parecido pero no idéntico suele quedar bien sin una corrección de color manual después. La dirección de la luz sigue importando —un rostro iluminado desde el otro lado sigue viéndose mal—, pero te quita de encima el desajuste más habitual.
La profundidad de la fusión se decide en cada par
Es un intercambio de cabeza inteligente: para cada par, el motor juzga si queda más natural fundir solo el rostro o la cabeza entera, y no hay ningún ajuste para forzar una opción u otra. Esa es la diferencia práctica con el resto de la línea, donde el nacimiento del pelo siempre se queda con el destino. También por eso un resultado puede volver con un nacimiento del pelo algo distinto del que esperabas: el motor decidió que la fusión completa era la más creíble de las dos.
Parámetros de la solicitud
| Parámetro | Obligatorio | Descripción |
|---|---|---|
image_url | Sí | La imagen que cambia. mínimo 1 caracteres |
reference_image_url | Sí | La imagen que aporta los rasgos faciales. mínimo 1 caracteres |
prompt | No | Opcional, pero conviene construir como si no estuviera. máximo 200 caracteres |
output_format | No | El formato de archivo de la imagen devuelta. |
output_quality | No | Calidad de imagen solicitada para el resultado, de 10 a 100 (por defecto 95). No cambia el costo. |
seed | No | Reutiliza una semilla para comparar dos ejecuciones sobre el mismo par de imágenes contra un sorteo idéntico, de modo que lo único que se mueva sea lo que cambiaste. |
Precios
$0.16 / imagen
Casos de uso
Flujos masivos de avatares y fotos de perfil
Una lista de pares destino-referencia pasa por el endpoint de forma programática, una llamada por par. Fija un seed por par cuando un reintento tenga que ser comparable con la primera ejecución, y elige WebP cuando los resultados vayan directo a la web.
Funciones para consumidores detrás de un formulario de subida
La interacción es una foto del usuario y una imagen que aportas tú. El usuario no tiene nada que configurar ni prompt que escribir, así que toda la función es un campo de formulario y un trabajo en segundo plano.
Catálogos y plantillas
Un mismo rostro de referencia sobre un conjunto de imágenes preparadas da una serie coherente sin regenerar ninguna. El ajuste de formato de salida entrega los archivos en la forma que tu flujo ya espera; cualquier accesorio que pida una plantilla tiene que estar en la imagen antes del intercambio.
Imágenes sin censura, donde el límite es el consentimiento y no el tema
SpicyAPI no añade ningún filtro de contenido propio ni pide un indicador de madurez, así que el cuerpo de la solicitud lleva los mismos campos muestre lo que muestre la imagen. Lo que no se relaja es la autorización: necesitas el consentimiento explícito e informado de la persona retratada para ese rostro concreto en ese material concreto, y que una foto sea pública nunca implica consentimiento.
Guía de prompts y consejos prácticos
El campo de instrucción aquí no hace nada
El modelo de base acepta prompt con un límite de 200 caracteres, pero no hemos conseguido que cambie nada.
| Lo que enviamos | Lo que volvió |
|---|---|
add mirrored aviator sunglasses | Sin gafas de sol; idéntico a no enviar nada |
wearing black sunglasses | Sin gafas de sol; idéntico a no enviar nada |
restyle the hair into a sleek straight bob | Pelo sin cambios |
soften the expression into a faint half smile | Expresión sin cambios |
a wide open-mouthed laugh | Expresión sin cambios |
Cinco llamadas reales el 20 de septiembre de 2026, cada una comparada con la misma solicitud con el campo vacío. No hay error ni advertencia, así que la respuesta no te permite saber que el valor se ignoró. Trabaja sin él: si necesitas un accesorio u otra expresión, ponlo en la imagen de destino antes del intercambio.
Lo que el motor decide por ti
Dos ejecuciones en este endpoint volvieron con decisiones opuestas, y es la forma más clara de verlo:
| Destino | Lo que se trasladó |
|---|---|
| Una coleta negra muy tirante | La cabeza entera: el pelo rojo de la referencia llegó con los rasgos |
| Pelo mojado peinado hacia atrás | Solo el rostro: el pelo del destino quedó tal como se fotografió |
Si necesitabas un accesorio u otra expresión
El campo de instrucción no te lleva hasta ahí, así que el cambio tiene que existir antes del intercambio:
| Lo que querías | Dónde hacerlo en su lugar |
|---|---|
| Gafas de sol, un sombrero, joyas | Pónselos a la persona de la imagen de destino antes de llamar a este endpoint |
| Otra expresión u otro peinado | Toma o genera así la imagen de destino; el intercambio conserva ambos |
Elegir el formato de salida y el seed
Define output_format cuando el tipo de archivo importe más adelante, porque convertir después implica recodificar: PNG para un archivo sin pérdida que vas a seguir editando, WebP para resultados que van directo a la web y JPEG si no indicas nada. Ninguno de los tres cambia el precio, así que elige el que necesita tu flujo, no el que creas más barato. Fija un seed solo cuando quieras comparar ejecuciones: da a dos ejecuciones sobre el mismo par la misma tirada, de modo que lo único que se mueve es la variable que cambiaste; es una herramienta de comparación, no la promesa de una imagen idéntica byte a byte. En producción, lo habitual es querer una tirada nueva cada vez.
Cuando el resultado no es el que querías
| Lo que ves | Qué cambiar primero |
|---|---|
| Una costura en la mandíbula pese al ajuste de tono | Usa una referencia iluminada desde la misma dirección: el tono se iguala, la dirección no |
| El nacimiento del pelo cambió y querías conservarlo | Es lo esperado aquí; usa Face Swap o Face Swap Pro |
| La instrucción no tuvo ningún efecto visible | Es lo esperado: el campo no actúa aquí; cambia la imagen de destino |
| Cambió la persona equivocada | Recorta el destino hasta dejar a una sola persona |
| Los rasgos se ven blandos o aproximados | Usa una referencia con el rostro más grande y nítido |
Elegir el endpoint adecuado
| Lo que necesitas | Endpoint |
|---|---|
| Ajuste de tono de piel y elección del formato de archivo | Este endpoint |
| Precisión en los puntos del rostro y la textura original, sin controles | Face Swap Pro |
| El intercambio simple con seed, sin tocar nunca el pelo | Face Swap |
| La cabeza completa, con el pelo, siempre | Head Swap |
| Un rostro a lo largo de un clip en movimiento | Video Face Swap |
Ejecutarlo por lotes
Dos campos obligatorios y tres valores por defecto convierten un lote en un bucle sobre pares. Envía cada llamada de creación con un Idempotency-Key y guarda el id de tarea junto al registro que la originó; si se corta una conexión, repetir la solicitud con la misma clave devuelve la tarea original en lugar de iniciar una segunda con un segundo cobro. Consulta cada pocos segundos y copia cada resultado a tu propio almacenamiento: los archivos generados se eliminan a los 14 días y las imágenes de origen subidas, al día siguiente.
Inicio rápido de la API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/face-swap-v1-plus/edit",
"input": {
"image_url": "https://example.com/reference.png",
"output_format": "jpeg",
"reference_image_url": "https://example.com/reference.png"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Consulta la referencia de la API para autenticación, el esquema completo, sondeo y gestión de errores.
