Cast Swap

A API do Cast Swap substitui as pessoas, o lugar ou os dois em um vídeo curto pelas suas próprias imagens de referência. O vídeo mantém o movimento, o enquadramento, o ritmo e o som. Você faz a cotação de uma execução de graça, inicia a execução e acompanha a tarefa dela como qualquer outra.

O Cast Swap só roda no Nodaro Cloud. Em uma instalação auto-hospedada, as duas rotas respondem 404. As rotas recebem um bearer token. Veja Autenticação.

Endpoints

O corpo da requisição

As duas rotas recebem o mesmo corpo.

Um papel indica alguém, ou o cenário, no vídeo, e recebe de 0 a 3 imagens de uma pessoa ou de um lugar:

• Uma pessoa: { kind: "person", name, images, body?, outfit?, hair? }. name diz quem é no vídeo, por exemplo "the woman dancing". Cada um de body, outfit e hair é "new", o padrão, que vem das suas imagens, ou "original", que mantém o do vídeo.
• O lugar: { kind: "location", name?, images }. O nome padrão é "the setting".

Um papel sem imagens, vazio ou null, mantém essa pessoa ou esse lugar como no vídeo. É preciso pelo menos um papel com imagens, ou um postPrompt.

{
  "videoUrl": "https://example.com/clip.mp4",
  "roles": [
    { "kind": "person", "name": "the woman dancing", "images": ["https://example.com/me.jpg"], "outfit": "original" }
  ],
  "preview": true
}

A cotação

POST /v1/cast-swap/estimate responde { totalCredits, breakdown: { castSwap, seedance }, settlesLower }.

• totalCredits é breakdown.castSwap, a execução em si, mais breakdown.seedance, o modelo de vídeo que ela chama.
• settlesLower: true significa que a duração do resultado fica a cargo do modelo, então a cobrança final deve ser menor que a cotação.

Repetições

Envie o mesmo cabeçalho Idempotency-Key, de 8 a 200 caracteres, quando tentar uma execução de novo. Uma repetição em cerca de 10 segundos responde 200 { jobId, deduped: true } com um cabeçalho X-Dedup-Hit: 1. Uma repetição posterior responde 202 { jobId } com a tarefa da primeira execução. Em ambos os casos, nada novo é iniciado nem cobrado. Sem uma chave, cada requisição é uma nova execução.

Erros

Toda recusa acontece antes de qualquer cobrança. O corpo é { error: { code, message } }.

Pelo SDK

client.castSwap encapsula as duas rotas. Ele também pode ser importado como @nodaro/sdk/cast-swap.

run(params: CastSwapParams, options?: { idempotencyKey?: string }): Promise<{ jobId: string; deduped?: boolean }>
estimate(params: CastSwapParams): Promise<CastSwapEstimate>

CastSwapParams é o corpo da requisição acima. CastSwapEstimate é a cotação. run() envia idempotencyKey sem alteração como o cabeçalho Idempotency-Key. Sem ele, nenhum cabeçalho é enviado.

const params: CastSwapParams = {
  videoUrl,
  roles: [{ kind: "person", name: "the woman dancing", images: [myPhotoUrl], outfit: "original" }],
  preview: true,
}
const quote = await client.castSwap.estimate(params)
const { jobId } = await client.castSwap.run(params, { idempotencyKey: crypto.randomUUID() })

Acompanhe a tarefa com client.jobs.get(jobId). A tarefa de uma prévia guarda todas as entradas no input_data dela, então você pode executá-la de novo com preview: false para renderizar o clipe inteiro com as mesmas escolhas.

Pelo MCP

A ferramenta MCP é cast_swap. Sem confirm, ela retorna a cotação e não cobra nada. Com confirm: true, depois que o usuário aceita o preço, ela inicia a execução e retorna um ID de tarefa.