Flujo de trabajo de API de intercambio de rostros con IA: subidas autorizadas, trabajos asíncronos y entrega fiable

Comparar fotos de referencia y el color antes de intercambiar.

En SpicyAPI, el Face Swap es una familia de endpoints sin censura que reciben dos imágenes (o una imagen y un clip), sin prompt y sin máscara. Esta guía explica qué endpoint llamar, cómo probarlo primero en el Playground y luego desde código o con un agente, qué revisar en la salida y cómo conservar el resultado después de que la plataforma lo borre.

Elegir el endpoint según el trabajo

Empiece con Face Swap a $0.013. Pase a Pro cuando el rostro intercambiado se vea más liso o más nítido que el resto del encuadre, y a Plus cuando las dos fotos tengan tonos de piel o colores de luz claramente distintos. 200 variantes de avatar cuestan $2.60 con Face Swap y $32 con Pro, así que pruebe su par más difícil en ambos. Plus tiene un campo prompt que no tiene ningún efecto, así que déjelo fuera y ponga las gafas o la expresión en la foto de destino en su lugar.

Video Face Swap factura el clip de origen en bloques completos de 10 segundos, así que un clip de 12 segundos se cobra como 20 segundos ($0.52) y uno de 40 segundos como $1.04. Al enviarlo se retiene la estimación de 40 segundos ($1.04) y se libera la diferencia cuando la tarea se liquida. Recorte hasta el límite de un bloque antes de enviar.

Qué hacen los endpoints con rostros reales

Estos endpoints se ofrecen sin censura: SpicyAPI no añade ningún escaneo de rostros por solicitud ni comprobación de personas reales. Los fallos suelen deberse a la entrada (ningún rostro detectable, un archivo inaccesible), aunque un modelo concreto puede rechazar una solicitud. La política de uso aceptable prohíbe la suplantación de identidad, el uso íntimo o sexualizado sin consentimiento de la apariencia de una persona real y cualquier cosa que involucre a menores; tras un aviso, SpicyAPI puede eliminar los materiales almacenados y suspender el acceso. Una foto pública o una relación previa no son consentimiento. El registro de consentimiento es suyo y debe estar antes del botón de subida:

• El usuario que ha iniciado sesión confirma que tiene el permiso de la persona retratada para ambas imágenes y para este uso; guarde la confirmación junto al proyecto (quién, qué material, qué uso, cuándo).
• Ninguna imagen de menores y ningún uso que suplante a una persona real para engañar.

Guarde esto como registros de producto, no en prompts, eventos de analítica ni registros del sistema.

Preparar entradas que no fallen

No hay ningún ajuste de intensidad que afinar, así que un mal resultado significa otro par de entradas.

• Rostros frontales, grandes y nítidos. Los ángulos de perfil marcados, el desenfoque por movimiento, la oclusión densa (manos, máscaras, gafas de sol grandes) y los rostros muy pequeños degradan la transferencia o hacen fallar la solicitud. Un rostro de referencia grande, nítido y frontal da el mejor resultado.
• La misma dirección de luz. El intercambio no vuelve a iluminar el destino, así que una referencia iluminada desde el lado contrario aparece como una costura en la línea de la mandíbula. Haga coincidir la dirección y el tono de piel aproximado, o elija otra referencia. Plus solo armoniza el tono de piel; no corrige un desajuste de dirección de luz.
• Un rostro por imagen. En fotos de grupo, Face Swap y Video Face Swap aceptan face_mapping: hasta 10 entradas, cada una empareja un rostro de referencia con un rostro de destino, numeradas desde 0 en orden de detección. Vuelva a comprobar la numeración cada vez que cambie una imagen. Plus y Pro asumen un solo rostro; recorte primero.

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

Esto intercambia el rostro de referencia 0 con el segundo rostro encontrado en el destino. Deje el campo fuera para intercambiar un solo rostro.

• Enlaces directos a archivos. Las URL de imagen deben resolver al archivo sin iniciar sesión. En vídeo, una página que reproduce el clip devuelve HTML en lugar de un clip, y la llamada falla con la devolución de la tarifa; suba el archivo en su lugar.
• Los papeles no son intercambiables. image_url es la imagen que se modifica; reference_image_url aporta el rostro. Intercambiarlos es una solicitud válida con otro resultado y sin error, así que un intercambio en la dirección equivocada parece un fallo del modelo.

Límites para vídeo: MP4 de hasta 90 MB y de 3 a 40 segundos, imagen de referencia JPG, PNG o WEBP de hasta 10 MB. Mantenga el rostro grande en el encuadre y no girado durante mucho tiempo. El endpoint funciona mejor con una sola persona en pantalla; para un clip con varias personas, añada face_mapping (la misma forma que arriba, numerada en orden de detección) o recorte hasta la persona.

Probarlo primero en el Playground

Abra la página de tareas de Face Swap y use la pestaña Playground (configurar, estimar, ejecutar). Introduzca la imagen de destino y la imagen del rostro de referencia, compruebe la estimación de precio para sus ajustes y ejecútelo. Pruebe aquí su par más difícil antes de escribir código: si el resultado es incorrecto en el Playground, también lo será desde la API, y la solución es otro par de entradas. Head Swap tiene la misma pestaña para intercambios de cabeza entera.

Luego llamarlo desde el código

Instale el SDK de Python (pip install spicyapi), defina SPICY_API_KEY en el entorno y ejecute:

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

Ejecute un proceso por archivo de trabajo. Si la espera agota el tiempo, vuelva a ejecutarlo con el mismo archivo para reanudar la tarea guardada. Si fue el propio envío el que agotó el tiempo antes de devolver un ID, conserve el archivo y concilie esa solicitud antes de volver a intentarlo; la protección de idempotencia no es permanente. Utilice un nombre de archivo de trabajo nuevo solo cuando quiera una solicitud de pago nueva.

Las subidas, la espera, los errores y los reintentos están en la guía de Subject Swap y en la referencia del SDK de Python. Video Face Swap usa spicyapi/face-swap-video-v1/video-edit con video_url y reference_image_url.

O dejar que un agente ejecute el trabajo

Si un asistente debe ejecutar los intercambios por usted, dele la CLI o el servidor MCP. Ambos muestran el precio y le piden confirmación antes de una llamada de pago. El Skill añade instrucciones a cualquiera de los dos.

• CLI. spicyapi ejecuta una tarea desde un terminal o script (npx @spicyapi/cli funciona sin instalar):

``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 contiene el mismo objeto input que antes, con los URI spicy://. Este bloque inicia un trabajo nuevo. Conserve la clave y el ID de tarea que imprime; tras un tiempo de espera, reanude esa tarea en lugar de volver a ejecutar el bloque con una clave nueva.

• Servidor MCP. Añada el servidor MCP a su asistente y luego pregunte: "Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap." Llama a spicyapi_upload_file, luego a spicyapi_task_create (que se detiene para que confirme el precio) y luego a 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 instala el Agent Skill, que enseña a un asistente de programación a leer el esquema en vivo, reutilizar claves de idempotencia y guardar resultados en lugar de adivinar. No puede ejecutar tareas por sí mismo, así que úselo junto con la CLI o MCP.

El registro de consentimiento y la copia de los resultados a su propio almacenamiento se aplican a las llamadas de un agente exactamente igual que a las suyas.

Revisar antes de darlo por terminado

succeeded significa que la generación ha terminado. Antes de descargar, compruebe que el material tiene una URL utilizable y que ni pending ni unavailable son verdaderos; mientras pending sea verdadero o falte la URL, siga consultando la misma tarea. Estar listo para la entrega tampoco significa que la imagen esté aprobada. En vídeo, revise los cortes y los movimientos rápidos, no solo el primer fotograma. Una puntuación de similitud es una señal de diagnóstico, no un consentimiento ni una aprobación de publicación.

Dos comprobaciones que cambian lo que hace a continuación:

• El pelo forma parte del diseño (un personaje de videojuego, una mascota). Face Swap conserva el peinado del destino, así que el rostro nuevo queda bajo el pelo viejo. Use Head Swap en su lugar, con una imagen fija de la ficha de personaje como referencia, y compare cada salida con la ficha: un rostro que se desvía sobre una composición estable es un problema de identidad, lo contrario es un problema de encuadre, y un reintento solo arregla uno de los dos.
• Un retrato en varios layouts. Ejecute Face Swap una vez por layout con la misma referencia y el mismo seed. Acepte una salida cuando el rostro sea reconocible frente al retrato en el recorte que va a publicar, cuando las gafas y la línea del pelo no se hayan desviado y no aparezcan personas adicionales; guarde la revisión de referencia, la revisión de destino y el ID de tarea junto con ella.

Entregar: copie usted mismo el resultado

Los materiales subidos se borran al día y los resultados como mucho a los 14 días (retention.outputsExpireAt tiene la hora exacta). Descargue el resultado y guárdelo usted mismo; el enlace del resultado dura unos 20 minutos. Consulte la guía de retención.

Cuando sale mal

FAQ

¿La API rechazará el rostro de una persona real?

SpicyAPI no comprueba: no hay verificación de persona real ni escaneo por solicitud, y los fallos suelen deberse a la entrada. Un modelo concreto puede rechazarla igualmente, y la política de uso aceptable prohíbe la suplantación de identidad, el uso íntimo sin consentimiento y a los menores. Construya usted mismo el registro de permisos.

¿Puedo enviar un vídeo y una imagen en una sola llamada?

Sí, en Video Face Swap: un MP4 y una foto de referencia. Para varias personas en un clip, use allí face_mapping o el flujo de Video Head Swap de dos pasos cuando necesite cabezas enteras.

¿API alojada o intercambio de código abierto autoalojado?

El endpoint alojado cuesta $0.013 por imagen y le quita el aprovisionamiento de GPU y el mantenimiento del modelo. El autoalojado sustituye las tarifas por imagen por costes de GPU y operativos; si sale más barato depende del volumen y la utilización. Un volumen alto y constante puede repartir esos costes entre más imágenes, pero sigue manteniendo los controles de consentimiento y retención.

¿Es lo mismo que una API general de edición de imágenes?

No. Un endpoint de intercambio recibe dos imágenes (o una imagen y un clip), sin prompt y sin máscara, y cada endpoint decide qué se conserva del destino: Face Swap conserva el pelo, Head Swap lo reemplaza. El mismo par de entradas puede fallar en la revisión de forma distinta en cada uno, así que elija primero el endpoint.

¿Debería conservar los retratos originales junto con la salida?

Solo si tiene una razón clara y una política de retención declarada. Los materiales subidos en SpicyAPI se borran igualmente al día, así que conserve los ID de revisión de referencia y de destino y el ID de tarea como linaje, en lugar de una copia permanente de cada retrato.

¿Necesito webhooks o basta con el sondeo?

El sondeo por sí solo funciona y es la vía de recuperación: lea cada pocos segundos, o añada wait (hasta 60 s) en createTask para intercambios de imagen cortos. Añada un webhook para menor latencia, guarde cada evento una sola vez y trate el sondeo como la conciliación de las devoluciones de llamada perdidas.

Lo que debe poder responder

Una función de intercambio de rostros gana confianza cuando su equipo puede decir qué imágenes se usaron, qué revisiones entraron, si la tarea se aceptó una sola vez, por qué se entregó un resultado y cómo se elimina. Los registros de consentimiento, las claves de idempotencia, su propio almacenamiento y un paso de revisión son lo que producen esas respuestas.