Substituição de pessoas

Alguns modelos não geram uma cena nova: eles substituem uma pessoa. Um rosto levado de uma foto para outra, uma cabeça inteira ou uma figura completa dentro de um clipe de vídeo. O catálogo reúne todos eles sob um mesmo rótulo, toolkit: "subject-swap", e eles existem em dois formatos — uma chamada ou duas chamadas com uma escolha no meio.

Fora isso, não têm nada de especial. São tarefas assíncronas comuns, seus parâmetros vêm do próprio inputSchema e seus resultados chegam em output.assets[].

toolkit avisa que o modelo é um desses

toolkit é um rótulo de classificação em um item do catálogo, presente tanto na resposta autenticada de GET /api/v1/models quanto no catálogo público. Hoje ele tem um único valor, subject-swap, e o campo não aparece nos modelos que não pertencem a nenhum kit — teste o valor, nunca a presença da chave.

O campo é apenas informativo. Ele não decide qual chave pode chamar um modelo, como a requisição é cobrada nem o que o modelo aceita. Trate um valor desconhecido como trataria um item desconhecido de badges: ignore.

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 linha é um endpoint que pode ser chamado. Quem define o resto desta página é a coluna tasks: uma family que tem um endpoint video-analyze é uma family de duas chamadas, e o endpoint video-edit correspondente não pode ser chamado sozinho.

Qual dos dois formatos estou vendo?

Os dois formatos são async: true: você cria uma tarefa e depois busca o resultado por polling ou webhook.

Uma chamada

Aqui não há nada diferente de qualquer outro modelo de edição. Leia o inputSchema do endpoint, preencha e crie a tarefa:

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, // um dos itens da consulta ao catálogo acima
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

Os nomes dos campos mudam de um endpoint para outro: alguns aceitam prompt, seed ou um formato de saída, outros não aceitam nada além das duas imagens. A lista válida é o schema; não leve nomes de campo de um endpoint para outro. Uma referência pode ser uma URL HTTPS pública, uma imagem pequena em Base64 dentro da própria requisição ou uma URI spicy:// já enviada; veja Mídia.

Duas chamadas

A primeira chamada olha o seu clipe e informa o que encontrou, como um conjunto ordenado de quadros de pré-visualização. Você decide quais serão substituídos. A segunda chamada faz o trabalho.

seu clipe ──▶ video-analyze ──▶ output.assets[0], [1], [2] …   (um quadro por alvo)
                                          │
                 você escolhe as posições │ 0 e 2
                                          ▼
          video-edit (analysis_task_id + swap_targets) ──▶ o clipe pronto

Por que não fazer tudo em uma chamada? Porque, em uma cena com quatro pessoas, uma chamada única teria de adivinhar a quem você se referia — e um palpite errado é um vídeo pronto e cobrado com a pessoa errada substituída. Dividir o trabalho torna a escolha explícita e conferível.

const analysis = await createTask({
  model: analyze.model, // o item cujos tasks incluem "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, // o item "video-edit" da mesma family
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // o mesmo valor em que a análise rodou
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

O que a segunda chamada confere antes de aceitar

Essas conferências acontecem na criação, então uma requisição recusada não cria nada e não reserva nada.

Quando a segunda chamada é recusada

Todos esses casos são HTTP 400 com código de negócio code: 400. O msg é um destes:

Quanto custam as duas chamadas

A análise e a substituição são duas tarefas separadas com dois preços separados, cada uma reservada e liquidada por conta própria. Uma segunda chamada recusada não custa nada; uma análise bem-sucedida é cobrada mesmo que você depois desista de substituir qualquer coisa.

• A análise costuma ser cobrada per_request: uma cobrança por chamada, não importa a duração do clipe nem quantos alvos ela encontre.
• A substituição costuma ser cobrada per_second, em blocos inteiros, e a duração vem do clipe e não de um campo que você preenche. Por isso o valor informado antes do envio corresponde ao clipe mais longo que o endpoint aceita: o valor informado é o valor reservado, a cobrança final sai da duração arredondada e nunca ultrapassa a reserva, e a diferença volta para o seu saldo quando a tarefa é liquidada. Ver aqui uma reserva maior que a cobrança final é o comportamento esperado. Leia Cobrança antes de fazer as contas.

Leia os dois preços no catálogo em vez de supô-los e peça uma cotação de cada chamada se o valor exato importar.

Próximos passos