Introducción
Video Head Swap Analysis lee un clip y devuelve una vista previa por cada cabeza que puede seguir, en un orden fijo: la primera imagen es la posición 0, la segunda la posición 1, y así sucesivamente. Esas posiciones son lo que recibe la llamada de reemplazo: miras las imágenes y devuelves los números.
Aquí no se genera nada y el clip no se modifica. Esta llamada produce la lista de objetivos con la que trabaja la llamada de reemplazo, y es la única manera de saber cuántas cabezas hay en una toma y cuál es cuál.
Análisis de video de Head Swap → Edición de video de Head Swap
Funciones y aspectos destacados
Eliges a partir de imágenes, no de coordenadas
La mayoría de los endpoints de reemplazo obligan a describir a quién te referías, o bien lo adivinan. Aquí el análisis te entrega los candidatos como imágenes numeradas. La ambigüedad sobre a quién se reemplaza queda resuelta antes de que se genere nada, que es también el momento en el que equivocarse todavía sale gratis.
Un análisis alimenta varios reemplazos
El resultado sigue sirviendo durante 24 horas. Prueba con una persona, mira cómo quedó y después manda otro juego de fotos de referencia contra el mismo análisis: el análisis se paga una sola vez. Pasadas las 24 horas las referencias vencen y hay que analizar el clip otra vez.
Lee el material tal como se filmó
El rastreo acompaña a cada cabeza a través de cortes, giros y oclusiones parciales. Se aceptan clips de 5 a 30 segundos, y el análisis reporta todas las cabezas que logra sostener durante la toma, no solo la que está al frente.
Parámetros de la solicitud
| Parámetro | Obligatorio | Descripción |
|---|---|---|
video_url | Sí | El clip que se va a analizar, de 5 a 30 segundos. mínimo 1 caracteres |
resolution | No | Resolución de rastreo. La llamada de reemplazo debe usar el mismo valor, así que elige la resolución que quieres que tenga el clip final. |
Precios
$0.08 / análisis
El análisis y el intercambio se cobran por separado.
Casos de uso
Revisar un clip antes de pagar por reemplazarlo
La llamada de reemplazo cuesta más que el análisis. Correr primero el análisis te dice si las cabezas que te importan son realmente rastreables en este material: el desenfoque fuerte, las oclusiones largas y los sujetos que salen de cuadro aparecen como una vista previa faltante o inestable.
Elegir a una sola persona entre varias
Analiza una escena con varias personas en cuadro, lee las vistas previas y devuelve solo la posición que querías. El reemplazo deja intactas a todas las demás.
Sostener el mismo reparto en toda una serie
Genera un lote de clips con cualquier modelo de video, analiza cada uno y usa las vistas previas para alinear el mismo objetivo en todas las tomas, de modo que la serie se lea continua.
Cualquier temática, con un intérprete que dio su consentimiento
La solicitud no cambia en nada según lo que muestre el material. El requisito de autorización que aparece en los límites de más abajo tampoco cambia: es una condición dura, no una clasificación de contenido.
Guía de prompts y consejos prácticos
Usa la misma resolución en las dos llamadas
Elige la resolución que quieres que tenga el clip terminado y úsala también aquí: la llamada de reemplazo tiene que correr con el mismo valor. No cambia lo que detecta esta llamada, solo el cuadro en el que trabaja el reemplazo.
Lee el orden de las vistas previas, no lo supongas
Las imágenes vuelven ordenadas, pero el orden refleja el rastreo, no el lugar en pantalla ni la importancia. La persona que está más a la izquierda no es necesariamente la posición 0. Mira las imágenes.
Manda el mismo video a las dos llamadas
La llamada de reemplazo necesita el clip idéntico: mismo archivo, misma codificación. Si omites video_url en la solicitud de reemplazo, se copia desde el análisis, que es la forma más segura de garantizar que coincidan.
Vuelve a analizar si cambia el material
Reconvertir, recortar o volver a exportar el clip invalida el análisis: las posiciones ya no apuntan a las mismas cabezas. Analiza el archivo que de verdad vas a reemplazar.
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/head-swap-video-v1/video-analyze",
"input": {
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# 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.
