Video Head Swap API: análisis, elección del objetivo y edición

Video Head Swap es un flujo de API de dos etapas: analiza un MP4 de 5 a 30 segundos, mira las vistas previas de cabezas numeradas y luego envía la posición elegida y los retratos de reemplazo a la edición. El rostro, el peinado, el color del pelo y la forma de la cabeza cambian; el cuerpo, el vestuario, el movimiento, el audio y todas las personas que no seleccionas se quedan como estaban.

Aquí ves primero cada cabeza detectada y nombras la que quieres, antes de pagar la edición. Edita un vídeo existente; no anima dos fotos fijas hasta convertirlas en una actuación (para eso, usa un modelo de imagen a vídeo).

Elige el intercambio adecuado

El intercambio de cara es la opción más barata y sencilla siempre que el pelo del clip pueda quedarse. El intercambio de cabeza compensa cuando el pelo nuevo forma parte del personaje, a cambio de una unión en el cuello que tienes que inspeccionar.

Prepara el origen y los retratos de referencia

Usa solo imágenes de personas que estás autorizado a procesar: la tuya, la de una persona intérprete con una autorización firmada o una cabeza generada. Todos los que aparecen deben ser adultos. Ambas llamadas son sin censura, así que SpicyAPI no añade ningún filtro de contenido y esa comprobación te corresponde a ti.

En este ejemplo, una persona adulta ficticia con chaqueta color óxido se vuelve hacia otra persona adulta durante una conversación de doce segundos. Sustituye solo la cabeza de la primera persona; conserva a la segunda persona, la ropa y el diálogo.

Exporta el origen final antes del análisis: MP4, hasta 90 MB, de 5 a 30 segundos. video_url acepta un enlace HTTPS público que devuelva el propio MP4, no una página HTML de reproductor, o un URI spicy:// del flujo de subida gratuito, que es la vía más fiable para un archivo local. Si más tarde recortas, cortas o reencodas el origen, vuelve a ejecutar el análisis.

Prepara entre 1 y 3 retratos de la misma persona adulta de reemplazo. Una vista frontal y otra de tres cuartos son un buen par de partida; añade un perfil si el origen contiene un giro considerable. Mantén el pelo y la edad aparente coherentes en toda la serie. Haz que coincida también con el clip: ilumina los retratos desde la dirección en la que está iluminado el plano, con la cabeza en un ángulo similar. La unión en el cuello es donde se nota el desajuste y ningún campo de la petición lo compensa. Las referencias de vestuario de cuerpo entero pertenecen al reemplazo de personaje; esta tarea necesita la cabeza y el pelo previstos claramente visibles.

Para una imagen de referencia ficticia, usa un briefing como este:

Retrato de referencia fotográfico de un hombre adulto ficticio, de unos 35 años, con pelo corto oscuro, barba cuidada y expresión neutra, con una camisa lisa completamente abotonada. Luz suave y uniforme, rostro y pelo sin obstrucciones, fondo sencillo. Vista frontal, sin otras personas, sin texto.

Crea los demás ángulos a partir de esa identidad aprobada en lugar de pedir personas no relacionadas de forma independiente. La edición no tiene campo prompt, así que las referencias cargan con todo el resultado.

Ilustración de un set de referencia con vista frontal, de tres cuartos y de perfil.

Pruébalo primero en el Playground

1. Abre la página de edición de Video Head Swap y quédate en la pestaña Playground, en la vista Form. Inicia sesión con una cuenta con saldo para ejecutar.
2. Paso 1, Find the people in your clip. Añade el clip en Input video (suelta el MP4 o usa Asset URL) y elige Resolution, 480p o 720p. La edición debe usar el mismo valor, así que elige el que quieras que tenga el clip final. Pulsa Find people in this clip ($0.08).
3. Paso 2, Choose who to replace. Cada cabeza detectada aparece como una vista previa numerada. Elige la que quieres y añade entre una y tres fotos de referencia de la persona adulta de reemplazo. Fija un Seed solo si quieres comparar los sets de referencia de forma justa; si no, omítelo.
4. Ejecuta la edición y después comprueba la mandíbula, el cuello, el pelo y el cuello de la camisa en el resultado con sonido.

El análisis se puede reutilizar durante 24 horas, así que puedes probar otro set de referencia desde las mismas vistas previas sin pagar el seguimiento otra vez. Cada edición aceptada, incluido un nuevo set de referencia o seed, es una tarea nueva de pago. Si ninguna vista previa muestra a la persona que quieres, un plano más claro es la solución: una cabeza que nunca se ve con claridad no se puede seguir, y un clip sin ninguna cabeza que se pueda seguir falla con la reserva liberada.

La página de análisis ejecuta el paso 1 por su cuenta; un análisis correcto se cobra aunque te detengas ahí.

Después ejecútalo desde código

Instala el SDK de Python (pip install spicyapi), define SPICY_API_KEY en tu entorno y guarda esto como swap.py. analyze imprime las URL de las vistas previas; edit toma el ID de tarea del análisis y la posición de vista previa que elegiste. La edición debe usar la misma clave de API y la misma resolución que el análisis, y ningún video_url: hereda el clip analizado.

import sys
import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

def run(model: str, input_data: dict) -> tuple[str, list]:
    task = client.create_task(model=model, input_data=input_data,
                              idempotency_key=str(uuid.uuid4()))
    final = client.wait_for_terminal(task["taskId"])
    if final["state"] != "succeeded":
        raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
    return task["taskId"], output_assets(final)

if sys.argv[1] == "analyze":
    task_id, previews = run("spicyapi/head-swap-video-v1/video-analyze", {
        "video_url": "https://your-media.example/conversation.mp4",
        "resolution": "720p",
    })
    print("analysis task:", task_id)
    for position, asset in enumerate(previews):   # position 0 is the first image returned
        print(position, asset["url"])
else:  # python swap.py edit <analysis_task_id> <position>
    _, outputs = run("spicyapi/head-swap-video-v1/video-edit", {
        "analysis_task_id": sys.argv[2],
        "resolution": "720p",
        "swap_targets": [{
            "object_index": int(sys.argv[3]),
            "image_urls": [
                "https://your-media.example/replacement-front.png",
                "https://your-media.example/replacement-three-quarter.png",
            ],
        }],
        "seed": 42,
    })
    print(outputs[0]["url"])  # copy the video to your own storage now

Ejecuta python swap.py analyze, abre todas las vistas previas y anota el número de la persona adulta que quieres (la posición 0 es la primera imagen devuelta, no una regla de izquierda a derecha; nunca recurras a la 0 si tu persona no está), luego python swap.py edit <analysis_task_id> 1. La edición acepta entre 1 y 10 objetivos con entre 1 y 3 imágenes de referencia de la misma persona cada uno; no hay entrada de máscara, vestuario, audio ni prompt. La creación, la espera, los reintentos, las claves de idempotencia y las descargas están cubiertos en la guía de tareas y en la referencia del SDK de Python; un archivo local pasa por el flujo de subida gratuito y vuelve como un URI spicy:// para video_url.

O deja que un agente lo ejecute

Cuando un asistente debe ejecutar las dos llamadas, las tres herramientas oficiales muestran el precio y te piden confirmación antes de una llamada de pago.

• CLI. Pon el objeto input del análisis (video_url, resolution) en analysis.json y luego:

``bash spicyapi tasks create --model spicyapi/head-swap-video-v1/video-analyze --input-file analysis.json --wait ``

Ejecuta la edición igual con edit.json. Consulta la documentación de la CLI; npx @spicyapi/cli funciona sin instalar nada.

• Servidor MCP. Añade el servidor MCP y luego pregunta: "Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." Sube el archivo con spicyapi_upload_file, llama a spicyapi_task_create, que se detiene para que confirmes el precio, y luego a spicyapi_task_wait. Elige tú la posición y después pide la edición.
• Skill. npx skills add spicyapi-ai/spicy-skill instala el Agent Skill, que hace que un asistente de código lea el esquema del modelo en vivo en lugar de adivinar campos.

Cómo se ve una edición terminada

El ejemplo de modelo publicado abajo es un clip de origen de diez segundos y su edición a 480p con un retrato de referencia. El pelo y el rostro cambian; el vestido, la forma de andar, la contraluz y la cámara se quedan. Comprueba primero la mandíbula y la línea del cuello, donde se nota un desajuste de luz o de ángulo.

Lo que cuesta

La edición cuesta $0.064 por segundo facturado a 480p y $0.12 a 720p. La facturación va en bloques de cinco segundos, con un mínimo de cinco segundos y un tope de treinta segundos. Un clip de 10 segundos a 480p cuesta $0.72 en total: $0.08 de análisis más $0.64 de edición.

Antes de la liquidación, la edición reserva el máximo de treinta segundos, $1.92 a 480p o $3.60 a 720p. Un clip de doce segundos a 720p queda retenido en $3.60 aunque su cargo de edición sea de $1.80; el resto se libera cuando la tarea se liquida.

Diagnostica por separado la selección, la identidad y la entrega

Ilustración de la revisión del pelo, el cuello de la camisa y una mano en primer plano.

Reproduce el vídeo devuelto con sonido. La edición conserva el audio y el movimiento corporal del origen; no cambia la voz de quien habla y el escenario no tiene garantizado ser idéntico píxel a píxel. Inspecciona también a la persona no seleccionada, especialmente durante los cruces. Si una mano cruza el rostro sustituido, recorre el contacto y la reaparición paso a paso en lugar de aprobar solo un primer fotograma atractivo.

Guarda el vídeo aceptado de inmediato en tu propio almacenamiento: los enlaces de resultado duran unos 20 minutos y los resultados se conservan como máximo 14 días, así que un ID de análisis, una imagen de vista previa y una URL multimedia temporal no son una copia permanente.