Sustitución de personas

Algunos modelos no generan una escena nueva: sustituyen a una persona. Una cara que pasa de una foto a otra, una cabeza entera o una figura completa dentro de un clip de vídeo. El catálogo los agrupa bajo una misma etiqueta, toolkit: "subject-swap", y existen en dos formas: una llamada o dos llamadas con una elección en medio.

No tienen nada más de especial. Son tareas asíncronas corrientes, sus parámetros salen de su propio inputSchema y sus resultados llegan en output.assets[].

toolkit te dice que el modelo es uno de estos

toolkit es una etiqueta de clasificación en una entrada del catálogo y aparece tanto en la respuesta autenticada de GET /api/v1/models como en el catálogo público. Hoy solo tiene un valor, subject-swap, y el campo no está en los modelos que no pertenecen a ningún kit: comprueba el valor, nunca la presencia de la clave.

Es un campo meramente informativo. No decide qué clave puede llamar a un modelo, ni cómo se cobra la petición, ni qué acepta el modelo. Trata un valor desconocido igual que una entrada desconocida de badges: ignóralo.

curl -s "https://api.spicyapi.ai/api/v1/models?modality=video" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  | jq -r '.data.items[]
      | select(.toolkit == "subject-swap" and .enabled and .available)
      | [.model, (.tasks | join(",")), .family] | @tsv'

Cada línea es un endpoint que puedes llamar. La columna tasks es la que decide todo lo demás de esta página: una family que tiene un endpoint video-analyze es una family de dos llamadas, y su endpoint video-edit asociado no se puede llamar por su cuenta.

¿Cuál de las dos formas tengo delante?

Ambas formas son async: true: creas una tarea y recoges el resultado por sondeo o por webhook.

Una llamada

Aquí no hay nada distinto de cualquier otro modelo de edición. Lee el inputSchema del endpoint, rellénalo y crea la tarea:

const created = await fetch('https://api.spicyapi.ai/api/v1/jobs/createTask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPICY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-8814-swap-1',
  },
  body: JSON.stringify({
    model: swap.model, // una de las entradas de la consulta al catálogo de arriba
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

Los nombres de los campos cambian de un endpoint a otro: unos aceptan prompt, seed o un formato de salida, y otros no aceptan más que las dos imágenes. El esquema es la lista buena; no traslades nombres de campos de un endpoint a otro. Una referencia puede ser una URL HTTPS pública, una imagen pequeña en Base64 dentro de la propia petición o una URI spicy:// ya subida; consulta Medios.

Dos llamadas

La primera llamada mira tu clip e informa de lo que ha encontrado, en forma de conjunto ordenado de fotogramas de vista previa. Tú decides cuáles sustituir. La segunda llamada hace el trabajo.

tu clip ──▶ video-analyze ──▶ output.assets[0], [1], [2] …   (un fotograma por objetivo)
                                          │
                    eliges las posiciones │ 0 y 2
                                          ▼
          video-edit (analysis_task_id + swap_targets) ──▶ el clip terminado

¿Por qué no en una sola llamada? Porque en una escena con cuatro personas, una llamada única tendría que adivinar a cuál te referías, y una mala suposición es un vídeo terminado y cobrado en el que se ha sustituido a la persona equivocada. Partir el trabajo hace que la elección sea explícita y revisable.

const analysis = await createTask({
  model: analyze.model, // la entrada cuyos tasks incluyen "video-analyze"
  input: {
    video_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
    resolution: '720p',
  },
});
const analysisTaskId = analysis.taskId;

{
  "state": "succeeded",
  "output": {
    "assets": [
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" },
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" }
    ]
  },
  "settled": true
}

const swapped = await createTask({
  model: edit.model, // la entrada "video-edit" de la misma family
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // el mismo valor con el que se ejecutó el análisis
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

Qué comprueba la segunda llamada antes de aceptar

Estas comprobaciones se hacen al crear la tarea, así que una petición rechazada no crea nada ni reserva nada.

Cuando se rechaza la segunda llamada

Todos estos casos son HTTP 400 con código de negocio code: 400. El campo msg es uno de estos:

Cuánto cuestan las dos llamadas

El análisis y la sustitución son dos tareas distintas con dos precios distintos, cada una con su propia reserva y su propia liquidación. Una segunda llamada rechazada no cuesta nada; un análisis correcto se cobra aunque después decidas no sustituir nada.

• El análisis suele cobrarse per_request: un cargo por llamada, dure lo que dure el clip y encuentre los objetivos que encuentre.
• La sustitución suele cobrarse per_second, en bloques enteros, y la duración sale del clip y no de un campo que rellenes tú. Por eso el importe que se te indica antes de enviar corresponde al clip más largo que acepta el endpoint: el importe indicado es el importe reservado, el cargo final se calcula sobre la duración redondeada y nunca supera la reserva, y la diferencia vuelve a tu saldo cuando la tarea se liquida. Ver aquí una reserva mayor que el cargo final es lo esperado. Lee Facturación antes de hacer cuentas.

Lee los dos precios del catálogo en lugar de darlos por supuestos y pide una cotización de cada llamada si el importe exacto importa.

Siguientes pasos