# Video Remake

> O Video Remake é o que se chama de motion control com IA ou character swap: troca as pessoas, os pets, os produtos ou o lugar de um vídeo pelas suas imagens.

Source: https://nodaro.ai/pt-BR/docs/developers/api/video-remake

A **API do Video Remake** substitui as pessoas, os pets, os produtos ou o lugar 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: o áudio do clipe é mantido, e o resultado tem a duração do clipe. 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 Video Remake é o que se costuma chamar de motion control com IA ou character swap (troca de personagem). Para fazer um único personagem de uma imagem parada repetir os movimentos de um vídeo, use o nó [Transferir movimento](https://nodaro.ai/docs/nodes/video/motion-transfer).

O Video Remake só roda no Nodaro Cloud. Em uma instalação auto-hospedada, todas as rotas do Video Remake respondem `404`. As rotas recebem um bearer token. Veja [Autenticação](https://nodaro.ai/docs/developers/api/authentication).

## Endpoints
| Método | Caminho | O que faz | Custo |
| --- | --- | --- | --- |
| `POST` | `/v1/video-remake/estimate` | Faz a cotação de uma execução. Nada é criado nem reservado. | Grátis |
| `POST` | `/v1/video-remake` | Inicia uma execução. Responde `202 { jobId }`. Acompanhe a tarefa com `GET /v1/jobs/:id`. | A execução cotada |
| `POST` | `/v1/video-remake/:jobId/full-quality/estimate` | Faz a cotação da versão em qualidade total de uma execução de rascunho. Nada é criado nem reservado. | Grátis |
| `POST` | `/v1/video-remake/:jobId/full-quality` | Finaliza um rascunho em 1080p, como uma nova tarefa. Veja [Qualidade total](#full-quality). | A execução cotada |
| `GET` | `/v1/video-remake/style-choice` | Diz, por motor, se você escolhe o `style` de uma execução ou se o Nodaro o fixou como Movimento, se o motor aceita execuções só de estilo e se uma execução do Preciso aceita um estilo artístico. Público: não precisa de login. Veja [Estilo](#style). | Grátis |
| `GET` | `/v1/video-remake/advanced` | Diz se a página do Video Remake mostra as opções avançadas dela. Público: não precisa de login. Veja [Estilo](#style). | Grátis |

## O corpo da requisição
As duas rotas recebem o mesmo corpo.

| Campo | O que faz |
| --- | --- |
| `videoUrl` | Obrigatório. O clipe de origem, de 4 a 30 segundos. |
| `roles` | Obrigatório. Até 6 papéis de pessoa, 1 papel de lugar, 3 papéis de pet e 3 papéis de produto. Veja abaixo. |
| `references` | Opcional. Até 5 referências fixas: coisas que o vídeo deve mostrar e que nenhum papel substitui. Veja [Referências fixas](#fixed-references). |
| `prePrompt` | Opcional. As suas próprias palavras, colocadas no início do prompt, antes das instruções dos papéis. Tem o mesmo limite e as mesmas menções `{role:N}` que `postPrompt`. |
| `postPrompt` | Opcional. As suas próprias palavras para o modelo, até 4.000 caracteres. Mencione um papel como `{role:N}`, em que N conta a partir de 1 sobre `roles`, incluindo os papéis vazios. |
| `preview` | Opcional. `true` renderiza 4 segundos do clipe, a partir de `previewStart`. |
| `previewStart` | Opcional. Onde a prévia começa, em segundos. O padrão é 0. |
| `engine` | Opcional. O motor: `"nodaro-prism"` (Nodaro Prism), o padrão, ou `"nodaro-pulse"` (Nodaro Pulse). Veja [Motores](#engines). |
| `style` | Opcional. Como a execução segue o clipe: `"precise"`, o padrão, ou `"motion"`. Veja [Estilo](#style). |
| `direction` | Opcional, só no Nodaro Prism. Um estilo artístico, `{ style: "<id>" }`, em que o ID é um dos do catálogo do seletor [Estilo](https://nodaro.ai/docs/nodes/creative-controls/style). Veja [Estilos artísticos](#art-styles). |
| `motionLength` | Opcional, só no Nodaro Pulse. Onde o clipe é cortado em segundos inteiros: `"cut-end"`, o padrão, ou `"cut-start"`. |
| `resolution` | Opcional. `"480p"`, o padrão, `"720p"` ou `"1080p"`. No Nodaro Pulse, `"720p"`, o padrão dele, ou `"1080p"`. |
| `draft` | Opcional. Desativado por padrão, então uma execução em 480p é uma execução comum. `true` faz um rascunho em 480p, cuja mesma tentativa a [qualidade total](#full-quality) pode finalizar em 1080p depois. `true` acima de 480p é recusado. O Nodaro Pulse não tem rascunho. |
| `prepareReferences` | Opcional. O padrão é `true`. Veja [Preparação das referências](#reference-preparation). |
| `quality` | Obsoleto. `"draft"` ainda funciona e significa um rascunho em 480p. Use `resolution` e `draft` no lugar. |
| `sessionId`, `origin` | Opcionais. A sessão em que o resultado é arquivado, e o rótulo de origem do seu app. |

Um papel indica alguém, algo ou o cenário no vídeo, e recebe de 0 a 3 imagens de uma só pessoa, pet ou produto, ou de um só lugar. Uma requisição recebe no máximo 30 imagens no total.

- **Uma pessoa:** `{ kind: "person", name?, images, body?, outfit?, hair? }`. `name` diz quem é no vídeo, por exemplo `"the woman dancing"`.
- **Um pet:** `{ kind: "pet", name?, images, body?, coat? }`.
- **Um produto:** `{ kind: "product", name?, images, shape?, finish? }`.
- **O lugar:** `{ kind: "location", name?, images }`. O nome padrão é `"the setting"`.

Um papel de pessoa, pet ou produto pode omitir `name`, ou enviá-lo vazio. O papel recebe então o nome da sua primeira imagem e é associado ao elemento do vídeo que melhor corresponde a ela. Esse papel precisa de pelo menos uma imagem. Um `name` tem no máximo 200 caracteres. Os papéis de uma execução de trend sempre têm nome.

Cada traço (`body`, `outfit`, `hair`, `coat`, `shape`, `finish`) é `"new"`, o padrão, que vem das suas imagens, ou `"original"`, que mantém o do vídeo.

Um papel sem imagens, vazio ou `null`, mantém essa pessoa, esse pet, esse produto ou esse lugar como no vídeo. É preciso pelo menos um papel com imagens, uma referência, um `prePrompt` ou `postPrompt`, ou um estilo artístico. Um estilo artístico só conta em uma execução só de estilo (veja [Estilos artísticos](#art-styles)).

Qualquer papel também pode receber duas configurações que valem só para uma prévia. Uma execução completa ignora as duas.

- `previewName` é o nome usado no lugar de `name` em uma prévia.
- `inPreview: false` deixa o papel fora de uma prévia. As imagens dele não são enviadas, preparadas nem cobradas. Uma menção `{role:N}` mantém o número e é lida como o `previewName` do papel, ou então como o `name` dele.

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

## Motores
`engine` escolhe o motor que faz o resultado. Omita-o para manter o Nodaro Prism.

| Motor | Resoluções | Rascunho | Qualidade total |
| --- | --- | --- | --- |
| `"nodaro-prism"`, Nodaro Prism (padrão) | 480p (o padrão), 720p, 1080p | Em 480p, com `draft: true` | Renderiza de novo em 1080p a própria tentativa de um rascunho |
| `"nodaro-pulse"`, Nodaro Pulse | 720p (o padrão), 1080p | Não | Nenhuma: execute de novo em 1080p |

- O **Nodaro Pulse** faz uma nova tentativa guiada pelo clipe e pelas suas imagens.
- `draft: true` no Nodaro Pulse é recusado com `draft_unsupported`, e `"480p"` com `resolution_unsupported`.
- O Nodaro Pulse renderiza segundos inteiros, então o clipe é cortado em segundos inteiros. `motionLength` diz onde: `"cut-end"` descarta a fração de segundo do fim, e `"cut-start"` a descarta do início. O Nodaro Prism ignora `motionLength`.
- Uma prévia tem 4 segundos a partir de `previewStart` nos dois motores.
- O Nodaro Pulse recebe no máximo 10 imagens por execução, somando todos os papéis e as referências fixas. Mais que isso é recusado com `too_many_images`. O Nodaro Prism recebe até 30.
- A tarefa registra o motor em `input_data.engine`, e a saída de uma tarefa concluída o indica em `engine`.

## Estilo
`style` diz como a execução segue o clipe. Omita-o para manter o estilo Preciso.

- `"precise"`, o padrão, segue o clipe exatamente.
- `"motion"` segue o movimento do clipe e tira das suas imagens a aparência das pessoas, dos animais de estimação e dos produtos. Ele segue o clipe com mais liberdade que o Preciso.

Os dois estilos mantêm o som e a duração do clipe. O Movimento pode custar um valor diferente do Preciso. Envie o mesmo `style` para `POST /v1/video-remake/estimate` para ver o preço exato.

A tarefa registra o `style` que você enviou em `input_data.style`. O campo fica ausente quando você omitiu `style`, o que significa Preciso. Uma execução de trend ignora `style`, porque a trend o decide.

O Nodaro pode fixar o estilo de um motor para todos como Movimento. Toda execução e toda cotação nesse motor são então do Movimento, seja qual for o `style` enviado. `GET /v1/video-remake/style-choice` diz qual, por motor, e não precisa de login:

```json
{ "engines": { "nodaro-prism": "user", "nodaro-pulse": "precise" } }
```

Cada valor é `"user"` (você escolhe, como acima), `"precise"` ou `"flex"` (Movimento, isto é, `style: "motion"`, fixado como acima). `"precise"` não muda nenhuma requisição. Os apps do próprio Nodaro rodam o Preciso nesse motor e escondem a escolha de estilo. Toda execução e toda cotação nesse motor usam o `style` enviado, como em um motor com a resposta `"user"`. Mostre uma escolha de estilo no seu app apenas para um motor com a resposta `"user"`.

A mesma resposta traz mais três mapas, cada um `{ "nodaro-prism": boolean, "nodaro-pulse": boolean }`:

- `styleOnly` diz se o motor aceita execuções só de estilo. Veja [Estilos artísticos](#art-styles).
- `preciseArtStyle` diz se uma execução do Preciso aceita um estilo artístico nesse motor.
- `preciseArtStyleAlone` diz se um estilo artístico sozinho é a mudança de uma execução do Preciso nesse motor, sem papel, referência ou prompt. A resposta é `false` até o motor aceitar essas execuções. O Nodaro pode executar essa requisição como uma execução do Movimento, e este mapa não diz isso. Veja [Um estilo artístico em uma execução do Preciso](#art-styles).

Os três dependem só do motor, então leia-os junto com `engines`. O Nodaro Pulse é sempre `false` nos três. Um servidor anterior a eles os omite: leia isso como `false` para todos os motores. Em um motor com a resposta `"flex"`, toda execução é do Movimento.

A resposta pode ter até um minuto de atraso. As trends não são afetadas.

**As opções avançadas da página do Video Remake.** A página do Video Remake oferece dois campos do corpo, `prepareReferences` e `prePrompt`, apenas nas opções avançadas dela. Essas opções ficam ocultas, a menos que o Nodaro as ative, com uma única configuração para a página inteira e para todos os motores. `GET /v1/video-remake/advanced` não precisa de login e responde `{ show: boolean }`, para que um app criado com esta API possa mostrar ou ocultar as mesmas opções. A resposta descreve apenas a página: toda execução e toda cotação aceitam `prepareReferences` e `prePrompt`, seja qual for a resposta. A resposta pode ter até um minuto de atraso. O SDK ainda não tem um método para ela, então leia-a com `client.request()`.

Enquanto a forma como o Nodaro prepara as execuções do Movimento para o motor limitar o clipe, uma execução completa do Movimento com um clipe de mais de 27,9 segundos é recusada com `clip_too_long_for_style`. No Nodaro Pulse, a duração é contada depois que o clipe é cortado em segundos inteiros. Uma prévia não tem esse limite.

## Estilos artísticos
`direction: { style: "<id>" }` desenha o vídeo em um estilo artístico, como `pop-art`. O ID é um dos do catálogo do seletor [Estilo](https://nodaro.ai/docs/nodes/creative-controls/style). Só o Nodaro Prism aceita um estilo artístico. O Nodaro Pulse o recusa com `400 art_style_needs_prism`.

**Reestilizar um clipe inteiro (só estilo).** Uma execução do Movimento (`style: "motion"`) pode receber um estilo artístico sem nada a trocar: nenhum papel com imagens e nenhuma referência fixa. A execução continua aceita, porque o estilo artístico é a mudança dela. Um `prePrompt` ou `postPrompt` continua sendo adicionado. A execução reestiliza o clipe inteiro e mantém as pessoas, os lugares, o movimento e o som.

- Ela é cobrada pelo que executa: a taxa base e o vídeo, sem a parte `privacy`. Uma parte `referenceAudio` só aparece quando a configuração do Nodaro para o motor executa essa etapa, e uma parte `prompt` só quando a configuração faz um modelo de linguagem escrever o prompt. Envie o mesmo corpo para `POST /v1/video-remake/estimate` para ver o preço.
- Por padrão, um estilo artístico em preto e branco sai monocromático. Em vez disso, o Nodaro pode executá-los como executa as outras execuções com estilo artístico, com o preço delas e sem deixá-los monocromáticos.
- Uma prévia segue o mesmo caminho da sua execução completa. Uma prévia que deixa de fora todos os papéis com imagens (`inPreview: false`) segue o caminho da sua execução completa, e o estilo artístico conta como a mudança da prévia.
- Ofereça isso apenas onde `GET /v1/video-remake/style-choice` responde `styleOnly: true` para o motor. Enquanto o Nodaro Prism tiver a resposta `false`, um estilo artístico sem mais nada a mudar é recusado com `400 validation_error`. Um com `prePrompt` ou `postPrompt` é aceito, mas roda como qualquer outra execução com estilo artístico.
- A execução ainda precisa ser do Movimento. Um motor com a resposta `"precise"` não muda nenhuma requisição, então uma execução do Movimento nele reestiliza o clipe como em um motor com a resposta `"user"`.

**Um estilo artístico em uma execução do Preciso.** Onde `GET /v1/video-remake/style-choice` responde `preciseArtStyle: true` para o motor, uma execução do Preciso também aceita um estilo artístico. O Nodaro pode fazê-la da forma como uma execução do Movimento é feita, em que um estilo artístico se mantém na imagem inteira de forma muito mais confiável. Nesse caso:

- A tarefa continua registrando o estilo que você enviou: `input_data.style` fica ausente, ou é `"precise"`. Ler a tarefa de volta, ou enviar o mesmo corpo de novo, pede a mesma execução.
- A cotação dela, enviada com o mesmo corpo, o preço, a qualidade total e o comportamento só de estilo são os de uma execução do Movimento.
- Sem mais nada a mudar, ela é aceita como uma execução só de estilo.
- `style-choice` não mostra qual caso se aplica. Leia a cotação para saber quanto uma execução custa.
- As tarefas feitas assim antes de o estilo ser mantido registram `input_data.style: "motion"`.

Caso contrário, a execução é feita como Precisa: o clipe é editado e as pessoas são trocadas como no Preciso, e o vídeo inteiro é desenhado no estilo artístico. Nesse caso:

- Aqui o estilo artístico não é uma mudança por si só. Uma execução do Preciso sem papel com imagens, sem referência fixa, sem `prePrompt` e sem `postPrompt` continua recusada com `400 validation_error`. Para só reestilizar um clipe inteiro, use uma execução do Movimento (só estilo, acima).
- O preço só muda onde a configuração do Nodaro para essas execuções primeiro redesenha as imagens dos papéis no estilo artístico. A cotação, enviada com o mesmo corpo, mostra isso.
- A tarefa registra o estilo artístico em `input_data.direction`.
- Onde `preciseArtStyle` é `false`, ou um servidor anterior a ele o omite, uma execução do Preciso com estilo artístico é recusada com `400 art_style_needs_flex`.

Um ID que não está no catálogo é recusado com `400 unknown_art_style`, e um painel de inspiração salvo com `400 art_style_not_supported`. `400 art_style_needs_flex` também responde a um estilo artístico em uma execução de trend e em uma execução do Movimento cujo prompt a configuração do Nodaro torna Preciso. Essa configuração não é o estilo fixado, e `style-choice` não a mostra.

## Referências fixas
`references` contém até 5 coisas que o vídeo deve mostrar e que nenhum papel substitui. Cada uma é `{ images, line }`:

- `images` contém de 1 a 3 imagens de uma coisa.
- `line` diz o que é a coisa, com 1 a 500 caracteres, por exemplo `"the glass she drinks from"`.
- `{image}` em uma linha representa a primeira imagem daquela referência, por exemplo `"Use {image} for the sky"`. Uma linha sem `{image}` o recebe no final.

As referências são enviadas como estão e nunca são preparadas. As imagens delas contam para o limite de 30. Uma referência sozinha basta para uma execução: nenhum papel precisa de imagens. Uma linha não pode mencionar um papel com `{role:N}`, porque uma linha descreve a própria coisa.

## Preparação das referências
A menos que `prepareReferences` seja `false`, as imagens de cada papel de pessoa, pet e produto viram primeiro uma única imagem de referência limpa, feita por um modelo de imagem. O vídeo é então feito a partir dessas imagens.

- A preparação custa créditos extras, mostrados como `breakdown.references` na cotação. Eles são cobrados quando ela é executada, mesmo que o vídeo falhe depois.
- Ela acrescenta cerca de um minuto.
- Se não for possível fazer a imagem de um papel, esse papel usa as suas próprias imagens.
- Os lugares não são preparados.

Envie `prepareReferences: false` para usar as suas imagens como estão.

## Preparação do clipe
O Nodaro define, para cada motor, como o clipe de origem é preparado para o modelo de vídeo. Por exemplo, ele decide se os rostos são ocultados antes, e se um clipe que o modelo recusa é tentado de novo uma vez. Uma execução não pode mudar isso. Um campo `faceMasking` enviado por um cliente mais antigo é aceito e ignorado.

A saída de uma tarefa concluída traz `privacy: { applied, reason }`. `applied` diz se o vídeo foi feito a partir do clipe preparado, e `reason` diz por quê.

## A cotação
`POST /v1/video-remake/estimate` responde `{ engine, totalCredits, expectedCredits, breakdown, privacyCredits?, settlesLower }`. A cotação indica dois totais.

- `totalCredits` é o que fica reservado quando a execução começa.
- `expectedCredits` é o que a execução deve cobrar. Ele nunca passa de `totalCredits`. A execução cobra o que ela realmente custa.
- No Nodaro Prism, o modelo escolhe a duração do vídeo, então o vídeo fica reservado na saída mais longa. Ele deve cobrar mais ou menos a duração do clipe de entrada, e o mesmo de saída. `settlesLower: true` indica isso: a cobrança final deve ser menor que `totalCredits`, perto de `expectedCredits`.
- No Nodaro Pulse, os dois totais são iguais e `settlesLower` é `false`. O Nodaro Pulse renderiza exatamente a duração pedida.
- `engine` é o motor da cotação.

`breakdown` indica as partes da cotação, só para exibição:

| Parte | O que é |
| --- | --- |
| `base` | A execução em si. |
| `references` | A preparação das referências. Vale 0 quando a preparação está desativada ou não há nada a preparar. |
| `motion` | O que o vídeo reserva. No Nodaro Pulse, o que o vídeo custa. |
| `motionExpected` | O que o vídeo deve cobrar, nunca acima de `motion`. Só no Nodaro Prism. |
| `privacy` | A preparação do clipe, quando a configuração do motor a faz. Entra nos dois totais quando sempre roda, e em nenhum quando é a repetição abaixo. |
| `prompt` | O prompt que um modelo de linguagem escreve para a execução, quando a configuração do motor pede um. |
| `referenceAudio` | A preparação do som do clipe para o modelo de vídeo, quando a configuração do motor executa essa etapa. |

`motion` e `motionExpected` são alternativas, então leia os totais, nunca a soma do detalhamento.

Quando a configuração do motor tenta de novo um clipe recusado, `privacyCredits` é a cobrança extra, feita só se essa repetição rodar. Ela não entra em nenhum dos totais. Para iniciar a execução, são necessários créditos para a reserva e para `privacyCredits`.

## 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.

## Qualidade total
Um **rascunho** concluído do Nodaro Prism pode ser finalizado em **qualidade total**. Um rascunho é uma execução do Video Remake ou de trend feita em 480p com `draft: true`. A qualidade total renderiza de novo a mesma tentativa em 1080p, ajustada ao clipe e com o áudio original do clipe. O resultado é uma nova tarefa, ligada ao rascunho, e o próprio rascunho continua existindo.

Só um rascunho tem qualidade total. Uma execução comum, incluindo uma execução em 480p feita sem `draft: true`, é recusada com `409 not_a_draft`. Para finalizar uma tentativa em 480p em 1080p depois, faça-a com `draft: true`. O Nodaro Pulse não faz rascunhos, então não tem qualidade total: execute de novo em 1080p. Uma qualidade total do Pulse feita antes dessa mudança continua listada como uma execução própria.

O `kind` da cotação é `"same-take"`. Um servidor mais antigo omite `kind`, o que significa o mesmo. A qualidade total fica disponível por 7 dias depois da conclusão do rascunho.

| Método | Caminho | O que faz |
| --- | --- | --- |
| `POST` | `/v1/video-remake/:jobId/full-quality/estimate` | Faz a cotação. Grátis: nada é criado nem reservado. Responde `{ kind, totalCredits, breakdown, availableUntil }`. |
| `POST` | `/v1/video-remake/:jobId/full-quality` | Inicia a finalização. Responde `202 { jobId }`. Quando a qualidade total desta execução já está em andamento ou concluída, responde `200 { jobId, existing: true }`, e nada novo é iniciado nem cobrado. Recebe um corpo opcional `{ sessionId }`. |

`:jobId` é o ID da tarefa do rascunho. Na cotação, `totalCredits` é `breakdown.base`, as etapas próprias da tarefa em qualidade total, mais `breakdown.motionHd`, a renderização em 1080p da tentativa do rascunho. `motionHd` vale 0 quando uma tentativa anterior deste rascunho que falhou já concluiu essa renderização: a renderização é reutilizada, e só a finalização é cobrada. `availableUntil` é quando terminam os 7 dias. O preço depende do rascunho, então faça a cotação antes.

Há uma única qualidade total por rascunho. A tarefa é identificada pelo rascunho, então uma requisição repetida ou simultânea responde a mesma tarefa, e um `Idempotency-Key` não é usado. Uma tentativa que falhou ou foi cancelada pode ser pedida de novo algumas vezes. A nova tarefa mantém o `origin` do rascunho, e `sessionId` a arquiva em uma das suas sessões.

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

| Status | `code` | Quando |
| --- | --- | --- |
| `401` | `unauthorized` | Nenhum usuário autenticado. |
| `402` | `insufficient_credits` | Os seus créditos não cobrem a finalização. Só no início. Em um espaço de trabalho, o limite que a recusou pode responder no lugar: `budget_exceeded`, `member_cap_exceeded` ou `user_allowance_exceeded`. |
| `404` | `not_found` | Não é uma tarefa sua, ou não é uma execução do Video Remake. Também um `sessionId` que você não pode usar, só no início. |
| `409` | `not_completed` | A execução não terminou. |
| `409` | `not_a_draft` | A execução não é um rascunho do Nodaro Prism. É uma execução comum, incluindo uma em 480p feita sem `draft: true`, ou uma execução do Nodaro Pulse, que não faz rascunhos: execute de novo em 1080p. |
| `409` | `full_quality_pending` | Não é definitivo, então tente de novo mais tarde. O corpo traz `retryable: true`. A renderização em 1080p de uma tentativa anterior deste rascunho está em revisão ou ainda não começou. |
| `409` | `full_quality_unavailable` | Definitivo. A execução não pode ser finalizada em qualidade total: nada foi guardado para renderizar de novo, o horário de conclusão dela não pode ser lido, ou a finalização em 1080p recusa este rascunho. Só no início, também quando todas as tentativas falharam ou nenhuma tentativa pode ser iniciada para esta execução. |
| `410` | `draft_expired` | Mais de 7 dias depois da conclusão do rascunho, ou o rascunho não pode mais ser finalizado em qualidade total. |
| `422` | `job_blocked` | A requisição foi bloqueada pela política de tarefas da implantação. Só no início. |
| `503` | `job_read_failed` | Não foi possível ler o rascunho agora. O corpo traz `retryable: true`. Tente de novo. |
| `503` | `estimate_unavailable` | A renderização em 1080p não pode ser cotada agora. Tente de novo em instantes. |
| `503` | `host_too_old` | Esta versão da plataforma não consegue executar a qualidade total. |

Diferencie `full_quality_pending` de `full_quality_unavailable` pelo código, não pela mensagem.

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

| Status | `code` | Quando |
| --- | --- | --- |
| `400` | `validation_error` | O corpo não é válido: nenhum papel com imagens, nenhuma referência, nenhum `prePrompt` ou `postPrompt` e nenhum estilo artístico (um estilo artístico só conta onde `styleOnly` é `true`), mais de 5 referências, uma referência sem imagem ou com mais de 3, mais papéis de um tipo do que o permitido, mais de 3 imagens em um papel, mais de 30 imagens no total, `draft: true` em 720p ou 1080p, um `prePrompt` ou `postPrompt` com mais de 4.000 caracteres, um `origin` inválido, ou um `style` diferente de `"precise"` ou `"motion"`. |
| `400` | `draft_unsupported` | `draft: true` com `engine: "nodaro-pulse"`, que não tem rascunho. |
| `400` | `resolution_unsupported` | `resolution: "480p"` com `engine: "nodaro-pulse"`. |
| `400` | `output_format_unsupported` | Uma saída MOV pedida a `engine: "nodaro-pulse"`. Só uma execução do Nodaro Prism pode retornar uma. |
| `400` | `too_many_images` | Mais de 10 imagens em uma execução do Nodaro Pulse, somando todos os papéis e as referências fixas. |
| `400` | `raw_reference_token` | O `name` ou o `previewName` de um papel, a `line` de uma referência, o `prePrompt` ou o `postPrompt` contém um token de referência bruto: `{image:`, `{video:` ou `{audio:`, em maiúsculas ou minúsculas. |
| `400` | `invalid_role_mention` | `prePrompt` ou `postPrompt` menciona `{role:N}` com N fora do intervalo de 1 ao número de papéis. Também qualquer `{role:N}` na `line` de uma referência. |
| `400` | `no_roles_in_preview` | Uma prévia que não mudaria nada, julgada pelo que envia: nenhum papel mantido nela que tenha imagens, nenhuma referência fixa, nenhum `prePrompt` ou `postPrompt` e nenhum estilo artístico. Uma prévia com todos os papéis deixados de fora ainda roda quando tem uma referência, um prompt ou, onde `styleOnly` é `true`, um estilo artístico. |
| `400` | `prompt_too_long` | O prompt ficaria longo demais. Um `{role:N}` é lido como o nome do papel quando o papel não tem imagens, então prompts dentro de 4.000 caracteres ainda podem somar mais que o limite do motor. O limite do Nodaro Pulse é de 8.000 caracteres. |
| `400` | `unsafe_url` | `videoUrl`, uma imagem de papel ou uma imagem de referência não é um endereço http ou https público. |
| `400` | `video_unreadable` | Não foi possível ler a duração do clipe. Ele não é um vídeo reproduzível. |
| `400` | `clip_out_of_range` | O clipe tem menos de 4 segundos ou mais de 30 segundos. |
| `400` | `clip_too_long_for_style` | Só com `style: "motion"`, enquanto a forma como o Nodaro prepara as execuções do Movimento para o motor limitar o clipe. Uma execução completa cujo clipe tem mais de 27,9 segundos. A mensagem é “This clip is too long for Motion. Use a shorter clip or choose Precise.” (este clipe é longo demais para o Movimento; use um clipe mais curto ou escolha o Preciso). |
| `400` | `prompt_parts_not_allowed` | O corpo envia `promptParts`. Só a própria plataforma Nodaro pode enviá-lo, para o prompt de uma trend. |
| `400` | `prompt_style_not_allowed` | O corpo envia `promptStyle`. Só a própria plataforma Nodaro pode enviá-lo. A redação de uma execução segue o `style` dela. |
| `400` | `preview_out_of_range` | Uma prévia passa do fim do clipe. `previewStart` mais 4 deve ser no máximo a duração do clipe. |
| `400` | `unnamed_role_needs_picture` | Um papel de pessoa, pet ou produto sem `name` e sem imagem. Um papel sem nome recebe o nome da sua primeira imagem, por isso precisa de uma. |
| `400` | `art_style_needs_prism` | Um estilo artístico com `engine: "nodaro-pulse"`, que não aceita nenhum. |
| `400` | `art_style_needs_flex` | Um estilo artístico em uma execução do Preciso onde `preciseArtStyle` não é `true`, em uma execução de trend ou em uma execução do Movimento cujo prompt a configuração do Nodaro torna Preciso. |
| `400` | `unknown_art_style` | `direction.style` não é um ID do catálogo do seletor Estilo. |
| `400` | `art_style_not_supported` | `direction` indica um painel de inspiração salvo, que uma execução do Video Remake não pode receber. |
| `400` | `role_name_required` | Uma execução de trend com um papel sem nome. Os papéis de uma trend sempre têm nome. |
| `401` | `unauthorized` | Nenhum usuário autenticado. |
| `402` | `insufficient_credits` | Os seus créditos não cobrem a execução. Só em `POST /v1/video-remake`. Quando a cotação traz `privacyCredits`, os créditos necessários são a reserva mais `privacyCredits`. Em um espaço de trabalho, o limite que a recusou pode responder no lugar: `budget_exceeded`, `member_cap_exceeded` ou `user_allowance_exceeded`. |
| `404` | `not_found` | `sessionId` indica uma sessão que você não pode usar. Só em `POST /v1/video-remake`. |
| `422` | `job_blocked` | A requisição foi bloqueada pela política de tarefas da implantação. Só em `POST /v1/video-remake`. |
| `503` | `host_too_old` | Esta versão da plataforma não consegue executar o Video Remake. |
| `503` | `estimate_unavailable` | O preço não pode ser cotado agora. Tente de novo em instantes. Só em `/estimate`. |

## Pelo SDK
`client.videoRemake` encapsula todas as rotas. Ele também pode ser importado como `@nodaro/sdk/video-remake`.

```ts
run(params: VideoRemakeParams, options?: { idempotencyKey?: string }): Promise<{ jobId: string; deduped?: boolean }>
estimate(params: VideoRemakeParams): Promise<VideoRemakeEstimate>
fullQualityEstimate(jobId: string): Promise<VideoRemakeFullQualityEstimate>
fullQuality(jobId: string, params?: { sessionId?: string }): Promise<VideoRemakeFullQualityResult>
styleChoice(): Promise<VideoRemakeStyleChoice> // GET /v1/video-remake/style-choice, public
```

`VideoRemakeParams` é o corpo da requisição acima, com `engine` tipado como `VideoRemakeEngine`, `style` como `VideoRemakeStyle` (`"precise" | "motion"`) e `motionLength` como `VideoRemakeMotionLength`. `faceMasking` continua tipado, para que o código antigo continue funcionando, mas está obsoleto e o servidor o ignora. `VideoRemakeEstimate` é a cotação. `run()` envia `idempotencyKey` sem alteração como o cabeçalho `Idempotency-Key`. Sem ele, nenhum cabeçalho é enviado. `styleChoice()` responde `VideoRemakeStyleChoice`, `{ engines: { "nodaro-prism", "nodaro-pulse" }, styleOnly?, preciseArtStyle? }`. Cada motor é um `VideoRemakeStyleChoiceOption`: `"user"`, `"precise"` ou `"flex"`. `styleOnly` e `preciseArtStyle` associam cada motor a um booleano; leia um valor ausente como `false`. `VideoRemakeParams` aceita `direction?: { style: string }`, e o `breakdown` da cotação pode indicar `referenceAudio`.

```ts
const { engines, styleOnly } = await client.videoRemake.styleChoice()
if (styleOnly?.["nodaro-prism"] === true) {
await client.videoRemake.run({ videoUrl, roles: [], style: "motion", direction: { style: "pop-art" } })
}
```

```ts
const params: VideoRemakeParams = {
videoUrl,
roles: [{ kind: "person", name: "the woman dancing", images: [myPhotoUrl], outfit: "original" }],
preview: true,
resolution: "480p",
}
const quote = await client.videoRemake.estimate(params)
const { jobId } = await client.videoRemake.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.

Para finalizar uma execução em 1080p, faça a cotação com `fullQualityEstimate(draftJobId)`, que é gratuita, e depois chame `fullQuality(draftJobId)`. O `kind` da cotação, um `VideoRemakeFullQualityKind`, é `"same-take"`. O resultado é `{ jobId, existing? }`. `existing: true` significa que a qualidade total desta execução já estava em andamento ou concluída, e nada foi cobrado. Uma recusa traz um `VideoRemakeFullQualityRefusalCode`. Em `full_quality_pending`, `err.details.retryable` é `true`: tente de novo mais tarde.

```ts
const quote = await client.videoRemake.fullQualityEstimate(draftJobId) // free
const { jobId, existing } = await client.videoRemake.fullQuality(draftJobId)
```

## Pela CLI
```bash
nodaro video-remake full-quality estimate <jobId> [--json]
nodaro video-remake full-quality run <jobId> [--session <id>] [--json]
```

`estimate` é uma cotação gratuita. Ela mostra os créditos, cada parte da cotação e até quando a execução pode ser finalizada. `run` gasta créditos e mostra o ID da nova tarefa. Quando a qualidade total já existe, `run` mostra essa tarefa e não cobra nada. `full_quality_pending` não é definitivo: execute o comando de novo mais tarde.

## Pelo MCP
A ferramenta MCP é [`video_remake`](https://nodaro.ai/docs/mcp/tools/video#video_remake). Ela recebe os mesmos campos em snake case, por exemplo `pre_prompt`, `prepare_references`, `in_preview`, `engine`, `style` e `motion_length`. Ela também recebe `art_style`, um estilo artístico no Nodaro Prism: um ID do catálogo do seletor [Estilo](https://nodaro.ai/docs/nodes/creative-controls/style), como `pop-art`. Ele funciona em uma execução do Movimento e em uma execução do Preciso onde o motor aceita um. Sem imagens de papéis e sem referências, ele reestiliza o clipe inteiro onde o motor aceita execuções só de estilo. Veja [`video_remake`](https://nodaro.ai/docs/mcp/tools/video#video_remake). Ela não recebe nenhuma configuração para a preparação do clipe. 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. As ferramentas `estimate_full_quality` e `full_quality` fazem a cotação e iniciam a versão em qualidade total de um rascunho ou de uma execução do Nodaro Pulse em 720p.

## Perguntas frequentes

### O que o Video Remake faz?

O Video Remake substitui as pessoas, os pets, os produtos ou o lugar em um vídeo curto pelas suas próprias imagens de referência. O movimento, o enquadramento, o ritmo e o som do vídeo continuam como estão, e o resultado tem a duração do clipe.

### O Video Remake é motion control ou character swap?

Sim. O Video Remake é o que se costuma chamar de motion control com IA ou character swap (troca de personagem). O movimento, o enquadramento, o ritmo e o som do clipe continuam, e as pessoas, os pets, os produtos ou o lugar vêm das suas imagens. Para fazer um único personagem de uma imagem parada repetir os movimentos de um vídeo, use o nó Transferir movimento.

### Qual pode ser a duração do vídeo de origem?

De 4 a 30 segundos. Um clipe mais curto ou mais longo é recusado com clip_out_of_range antes de qualquer cobrança.

### Como sei quanto uma execução do Video Remake custa?

Chame POST /v1/video-remake/estimate com o mesmo corpo que você vai executar. A chamada é gratuita e retorna totalCredits, o valor reservado quando a execução começa, e expectedCredits, o valor que a execução deve cobrar. Leia os dois totais, nunca a soma do detalhamento.

### Posso testar o visual antes de renderizar o clipe inteiro?

Sim. Envie preview como true para renderizar 4 segundos do clipe, a partir de previewStart. Uma prévia custa menos, e a tarefa dela guarda todas as entradas, então você pode executá-la de novo com preview como false.

### Posso finalizar uma execução de rascunho em qualidade total?

Sim, até 7 dias depois da conclusão do rascunho. Faça a execução com draft como true em 480p no Nodaro Prism. Depois, POST /v1/video-remake/:jobId/full-quality renderiza de novo a mesma tentativa em 1080p, como uma nova tarefa. Faça a cotação antes, de graça, com a rota de estimativa.

### Quais motores o Video Remake pode usar?

Dois. O Nodaro Prism é o padrão e renderiza em 480p, 720p ou 1080p, e faz um rascunho em 480p quando você envia draft como true. Envie engine como nodaro-pulse para usar o Nodaro Pulse, que renderiza em 720p ou 1080p, não tem rascunho e faz uma nova tentativa guiada pelo clipe e pelas suas imagens.

### Posso escolher se os rostos do meu clipe são mascarados?

Não. O Nodaro define, para cada motor, como o clipe de origem é preparado, inclusive se os rostos são ocultados antes. Um campo faceMasking enviado por um cliente mais antigo é aceito e ignorado.

### O Video Remake funciona em uma instalação auto-hospedada?

Não. O Video Remake só roda no Nodaro Cloud. Em uma instalação auto-hospedada, todas as rotas respondem 404.
