Use Character Swap cuando el reemplazo deba cambiar el aspecto completo de una persona, incluida la complexión y la ropa, mientras la escena, el movimiento de cámara y el audio original se mantienen. Character Swap le permite elegir a qué persona del clip se cambia: analice el clip final, revise las vistas previas numeradas y luego envíe el índice de vista previa elegido junto con una a tres imágenes del reemplazo. Si la ropa original debe mantenerse, use en su lugar un flujo de head swap o face swap.
En SpicyAPI, el análisis y la edición son tareas de pago separadas. Un clip de siete segundos cuesta en total $0.72 a 480p o $1.28 a 720p: un análisis más la edición, que redondea hacia arriba hasta diez segundos. El Playground ejecuta ambos pasos en el navegador y la API acepta las mismas entradas. Necesita autorización tanto para el material como para la semejanza de la persona en las imágenes de referencia.
Prepare una escena de siete segundos y un reemplazo de cuerpo completo
Nuestro ejemplo es un plano de siete segundos de alguien que lleva una caja de herramientas cerrada hasta un banco mientras otro adulto está de pie a su lado. La persona que transporta se reemplaza por una adulta ficticia con chaqueta de trabajo azul marino y pantalón gris carbón, el aspecto de las ilustraciones de abajo. El banco, la caja de herramientas, la otra persona y la actuación original se mantienen.
Exporte exactamente el clip de siete segundos que quiere editar. Conserve el agarre inicial, la acción de transportarlo y la liberación cuando la caja de herramientas llega al banco. La entrada es un MP4 de 5 a 30 segundos de hasta 90 MB. Subir el archivo es la vía más fiable; un enlace directo debe apuntar al propio MP4, porque una página con un reproductor falla (se devuelve el cargo). Recortar o recodificar después del análisis exige un análisis nuevo.
El tracker sigue a las personas que se mantienen razonablemente grandes y visibles, así que corte al tramo que importa y evite periodos largos en los que la persona que quiere está completamente oculta. Un corte más corto también cuesta menos, porque la edición se factura en bloques de cinco segundos.
Para el reemplazo, prepare una vista de cuerpo completo frontal y otra de tres cuartos de la misma adulta, con el mismo atuendo. Se acepta una referencia clara; tres es el máximo por objetivo. Un retrato de cabeza y hombros deja la complexión y la ropa al cálculo, así que muestre mangas, manos y calzado, e ilumine las referencias como el material en lugar de elegir el retrato más nítido. No combine el rostro de una persona, el pantalón de otra y una chaqueta diferente en la tercera imagen. El servicio recibe eso como referencias para un reemplazo, no como capas de ropa asignadas por separado.
Un briefing utilizable para generar la imagen es:
Retrato de referencia de cuerpo completo de una mujer adulta ficticia, de unos 30 años, con chaqueta de trabajo azul marino lisa, pantalón gris carbón y zapatos planos oscuros. Pose relajada de frente, manos visibles, mangas y calzado legibles, fondo neutro. Sin caja de herramientas, sin otras personas, sin letras.
Genere o fotografíe un segundo ángulo del mismo diseño ya establecido si hace falta. La edición de character swap no tiene campo de prompt de texto, ni selector de ropa ni máscara de cuerpo, así que la ropa deseada tiene que estar en las imágenes de referencia.
Ilustración de un juego de referencias de cuerpo completo, frontal y de tres cuartos.
Pruébelo primero en el Playground
- Abra la página del modelo Video Character Swap y quédese en la pestaña Playground en la vista Form. Inicie sesión con una cuenta con saldo para ejecutar.
- En Step 1, Find the people in your clip, añada el MP4 de siete segundos en Input video (subirlo es más fiable que un enlace) y elija la Resolution que quiere para el clip final,
480po720p. La edición debe usar el mismo valor. - Pulse Find people in this clip ($0.08). Todas las personas detectadas aparecen en Step 2, Choose who to replace, una vista previa recortada por persona.
- Elija la vista previa de la persona que lleva la caja de herramientas, añada una a tres imágenes de referencia del reemplazo y ejecute la edición. Un Seed es opcional.
La posición 0 es la primera vista previa devuelta, no necesariamente la persona más a la izquierda o la más grande, porque el orden viene del rastreo y no de la posición en pantalla. Si la persona que transporta es la segunda vista previa, ese es el índice 1. Mantenga el orden devuelto al guardar vistas previas: nombres de archivo alfabéticos o una galería ordenada pueden cambiar el índice en silencio.
Si la persona prevista no tiene vista previa, no pague una edición adivinando un número cercano. Ninguna imagen de referencia puede recuperar a una persona que no tiene vista previa, así que use una toma en la que esa persona se vea claramente. Un análisis que no encuentra a nadie termina como fallido y se libera su reserva; un análisis exitoso se cobra aunque decida no hacer el swap.
Después, llámelo desde el código
Instale el SDK de Python (pip install spicyapi), defina SPICY_API_KEY y ejecute lo siguiente. Sube el clip y dos referencias, ejecuta el análisis, imprime los enlaces de las vistas previas, pregunta qué índice cambiar y luego envía la edición. Ambas tareas se cobran.
import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
RESOLUTION = "720p" # must be identical in both calls
clip = client.upload_file("./workshop-seven-seconds.mp4")
front = client.upload_file("./replacement-front.png")
angled = client.upload_file("./replacement-three-quarter.png")
analysis_task = client.create_task(
model="spicyapi/character-swap-v1/video-analyze",
input_data={"video_url": clip["uri"], "resolution": RESOLUTION},
idempotency_key=str(uuid.uuid4()), # new key per new request; reuse only to retry the same one
)
print("Resume analysis:", analysis_task["taskId"], flush=True)
analysis = client.wait_for_terminal(analysis_task["taskId"])
if analysis["state"] != "succeeded":
raise RuntimeError(f"Analysis {analysis_task['taskId']} ended as {analysis['state']}")
previews = output_assets(analysis)
if not previews or any(p.get("pending") or p.get("unavailable") or not p.get("url") for p in previews):
raise RuntimeError(f"Analysis {analysis_task['taskId']} has no ready previews; retrieve it before editing")
for index, preview in enumerate(previews): # keep the returned order
print(index, preview["url"])
chosen = int(input("Index of the person to replace: "))
if not 0 <= chosen < len(previews):
raise ValueError("Choose one of the returned preview indices before creating an edit")
edit_task = client.create_task(
model="spicyapi/character-swap-v1/video-edit",
input_data={
"analysis_task_id": analysis["taskId"], # video_url is inherited from the analysis
"resolution": RESOLUTION,
"swap_targets": [{"object_index": chosen,
"image_urls": [front["uri"], angled["uri"]]}],
"seed": 42,
},
idempotency_key=str(uuid.uuid4()), # new key per new request; reuse only to retry the same one
)
print("Resume edit:", edit_task["taskId"], flush=True)
edit = client.wait_for_terminal(edit_task["taskId"])
if edit["state"] != "succeeded":
raise RuntimeError(f"Edit {edit_task['taskId']} ended as {edit['state']}")
assets = output_assets(edit)
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 {edit_task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"]) # copy it to your own storage nowLas subidas, la espera, los errores y los reintentos están en la guía de subject swap, la documentación de tareas y la referencia del SDK de Python. Use la misma clave de API para ambos pasos y ejecute la edición dentro de las 24 horas siguientes al análisis (un clip subido también caduca a las 24 horas); un análisis puede alimentar varias ediciones facturadas por separado. Las personas que no liste quedan intactas, y un índice pertenece a este análisis, así que no lo reutilice como ID de personaje en otro plano.
La intención de un reemplazo de personaje completo es conservar la escena, el movimiento de cámara, la coreografía y el audio original. Ese alcance no promete píxeles de fondo sin cambios ni una voz nueva.
O deje que un agente lo ejecute
Si un asistente debe ejecutar el swap, dele la CLI o el servidor MCP. Ambos muestran el precio y le piden confirmar antes de una llamada de pago. La Skill añade instrucciones por encima de cualquiera de los dos.
- CLI.
spicyapiejecuta una tarea desde un terminal (npx @spicyapi/clifunciona sin instalar):
``bash spicyapi files upload ./workshop-seven-seconds.mp4 # prints a spicy:// URI spicyapi tasks create --model spicyapi/character-swap-v1/video-analyze \ --input-file analysis.json --idempotency-key workshop-analysis-v1 --wait ``
analysis.json contiene {"video_url": "spicy://...", "resolution": "720p"}. Mire las vistas previas y luego ejecute el comando con video-edit, su propia clave workshop-edit-v1 y un input.json con analysis_task_id, resolution y swap_targets. Reutilice una clave solo para una petición sin cambios; una fuente, un objetivo o un conjunto de referencias nuevo necesita una clave nueva.
- Servidor MCP. Añada el servidor MCP (su fragmento de configuración está en esa página) a su asistente y luego pregunte: "Analiza ./workshop-seven-seconds.mp4 a 720p con Character Swap y muéstrame las vistas previas." Después de elegir la persona, diga: "Reemplaza el índice 1 usando ./replacement-front.png y ./replacement-three-quarter.png." Llama a
spicyapi_upload_file, luego aspicyapi_task_create(que se detiene para su confirmación de precio) y luego aspicyapi_task_wait. - Skill.
npx skills add spicyapi-ai/spicy-skillinstala la Agent Skill, que enseña a un asistente de programación a leer el esquema en vivo y reutilizar claves de idempotencia. No puede ejecutar tareas por sí mismo, así que úsela con la CLI o MCP. Qué vista previa cambiar sigue siendo su decisión.
Entienda el cargo antes de hacer variantes
Los precios provienen del catálogo público (octubre de 2026).
| Etapa | Precio | Ejemplo con siete segundos |
|---|---|---|
| Análisis | $0.08 por petición | $0.08 |
| Edición, 480p | $0.064 por segundo facturado | 10 segundos facturados: $0.64 |
| Edición, 720p | $0.12 por segundo facturado | 10 segundos facturados: $1.20 |
La duración de la edición se redondea a bloques completos de cinco segundos, con un mínimo de cinco segundos y un tope de treinta segundos. Una fuente de 5 segundos usa un bloque; 5,1 segundos usan dos. Antes del envío, la estimación de la edición reserva el máximo de treinta segundos, $1.92 a 480p o $3.60 a 720p, y la diferencia se devuelve cuando la tarea se liquida. Una comprobación de presupuesto debe por tanto permitir la reserva, no solo el importe final esperado. Una petición rechazada en la creación (resolución distinta, ID de análisis equivocado, índice repetido) no crea ni cobra nada.
Dos ediciones a 720p de la fuente de siete segundos, reutilizando un análisis, cuestan $2.48 en total: $0.08 más dos veces $1.20. Cambiar las referencias o el seed es una edición de pago nueva, no una revisión gratuita.
Repare el problema correcto
| Síntoma | Acción |
|---|---|
| La edición cambia a la persona de al lado | Vuelva a abrir las vistas previas ordenadas originales y corrija object_index; nuevas imágenes de referencia no arreglan una selección equivocada |
| La petición dice que el análisis no se encontró o pertenece a otro modelo | Use el ID de tarea de su propia tarea video-analyze, creada con la misma clave de API |
| La petición rechaza la fuente o la resolución | Omita video_url en la edición, use la resolución analizada o analice de nuevo la fuente nueva |
| El análisis es demasiado antiguo | Ejecute el análisis de nuevo y elija el objetivo en las vistas previas nuevas |
| La cara está bien pero cambia la ropa | Use referencias de cuerpo completo coherentes que muestren la misma chaqueta, el mismo pantalón y el mismo calzado |
| El reemplazo parece pegado | Las referencias están iluminadas de forma distinta al material; rehágalas con la misma dirección de luz y el mismo tono |
| Las manos atraviesan la caja de herramientas | Use un agarre más claro o un reemplazo con proporciones más compatibles; un retrato nítido por sí solo no describe el contacto |
| La identidad cambia después de un cruce | Pruebe una fuente con menos oclusión sostenida; inspeccione el retorno desde detrás de la otra persona |
| La tarea terminó bien pero el archivo está pendiente | Siga recogiendo la tarea existente; no cree otra edición de pago para recuperar una descarga |
Ilustración de la revisión de un fotograma impreso.
Observe a la persona que transporta, la caja de herramientas y el adulto no seleccionado juntos a velocidad normal. Después inspeccione el agarre, el contacto con el banco y la liberación. Una cara nueva puede verse excelente mientras la acción central falla. Si solo el último medio segundo tiene un defecto, puede bastar con recortar; si el agarre está roto de principio a fin, elija una fuente más clara o use un alcance de reemplazo de cabeza más estrecho cuando el cuerpo y la ropa originales puedan quedarse.
Copie el clip aceptado a su propio almacenamiento antes de que caduque: los resultados se conservan unos 14 días (véase retención y entrega de medios).
