API Pro: gerar vídeos com som

Um clip a partir de um prompt, ou uma animação de uma imagem que forneces. O ficheiro é um MP4, com som quando o pedires.

Submeter um vídeo

POST /videos

{ "prompt": "a woman in a white linen dress walks along a beach at sunset, wind in her hair, she turns and smiles at the camera",
  "width": 1080, "height": 1920, "audio": true }

Taxa de fotogramas predefinida: 30 fps. Os clips costumavam ser renderizados a 24 fps. Sem fps, um clip com o mesmo length é portanto mais curto do que antes (241 fotogramas: 8 s em vez de 10 s). Envia "fps": 24 para manter o comportamento anterior.

A resposta:

{ "jobId": "...", "seed": 908172, "cost": 30 }

O custo é calculado e anunciado no momento da submissão, antes de qualquer débito. A seed também é devolvida, independentemente de a teres fornecido ou de ter sido gerada aleatoriamente.

Formatos e preço

Um vídeo tem preço por formato, como taxa fixa independente da sua duração. Base: 5 créditos.

A taxa fixa é multiplicada por 2 a 720p e por 3 a 1080p, e depois o som duplica o preço. Os fatores aplicam-se à taxa base, não uns aos outros: 1080p com som custa 5 x 3 x 2 = 30 créditos. Até 481 fotogramas, ou seja 20 s a 24 fps, a duração não altera nada (5 s ou 20 s, a mesma taxa). Além de 481 fotogramas (até 721, apenas com consistency enhanced, comprimento fixo), o preço do formato é duplicado. A taxa de fotogramas (fps) não altera o preço, mas os patamares contam fotogramas: a 30 fps, o preço normal vai até 16 s; a 60, até 8 s (12 s ao dobro do preço em enhanced).

Uma exceção: em Qualidade, 480p sem som custa 2 créditos, independentemente da duração (desde 11 de outubro de 2026). Multi-Ref e coerência reforçada mantêm a taxa fixa do formato, 5 créditos.

O tamanho que recebes de volta. O motor trabalha em múltiplos de 32 e em duas fases, por isso o ficheiro sai a 768 x 1280 (ou 1280 x 768) para 720p e 1088 x 1920 (ou 1920 x 1088) para 1080p. O 480p mantém-se a 480 x 832 (ou 832 x 480), exceto em coerência reforçada. Útil de saber se juntas ou sobrepões as nossas renderizações.

O modo turbo foi retirado a 11 de outubro de 2026: um pedido turbo é renderizado em Qualidade 480p e tem o preço correspondente (2 créditos sem som, 10 com som).

Saber o preço antes de submeter

POST /videos/quote aceita o mesmo corpo que POST /videos e executa o mesmo cálculo, mas nada é criado: sem renderização, sem créditos retidos, sem consumo de quota. Chama-o antes de confirmar, especialmente a partir de um agente a trabalhar com um orçamento.

{ "cost": 30, "mode": "ltx25", "format": "1080p", "audio": true, "fps": 30, "duration_auto": true,
  "seconds_max": 16, "detail": "flat 5 x 3 (1080p) x 2 (sound) = 30" }

detail explica o valor; fps é a taxa de fotogramas usada, e seconds_max a duração em segundos a essa taxa. Com "consistency": "enhanced", a cotação aceita um comprimento fixo até 721 fotogramas e aplica a taxa acima de 481 fotogramas (x 2 (over 20 s) em detail a 24 fps, x 2 (over 481 frames) a outra taxa). A mesma rota existe para imagens, POST /images/quote, que responde sempre { "cost": 1, ... }: uma imagem custa sempre 1 crédito.

Para um clip Ultra faturado ao segundo, o orçamento dá a duração faturada em seconds, e detail detalha o preço por segundo.

Consultar, descarregar, cancelar

As mesmas rotas que as imagens, em /videos.

• GET /videos/{jobId}: pending / completed / failed, mesmos campos. Uma extensão reforçada pode terminar como failed com "error": "extension_not_applied" (o motor não aproveitou o final do clip anterior): nada é debitado, submete novamente.
• GET /videos/{jobId}/file: o MP4 (Content-Type: video/mp4).
• POST /videos/{jobId}/cancel: cancela, sem qualquer débito.

Em Ultra faturado ao segundo, uma renderização já em cálculo já não para: o cancelamento responde 409 render_in_progress, e o clip é entregue e faturado. Um clip que o motor recusa à saída termina em failed, com uma frase em detail e o código do motor em reason: nada é debitado.

Um vídeo demora 1 a 5 minutos, mais quando o motor arranca a frio. Consulta de 3 em 3 segundos e descarrega assim que o estado for completed: o ficheiro não é arquivado.

Vários planos num único clip

Um único prompt pode conter vários planos com cortes diretos, até 20 segundos no total a 24 fps (16 s a 30, o valor predefinido). Descreve-os por ordem: Shot 1: <enquadramento>, <ação>. Cut to Shot 2: .... Repete em cada plano o que tem de se manter igual (personagem, roupa, lugar, luz), e termina com uma linha de ambiente comum.

Não incluas códigos de tempo: mantém duration_auto ativo, e o motor escolhe a duração (até 20 s a 24 fps, 16 s a 30) e onde cortar. Dois a quatro planos por clip funcionam melhor.

A cinematic sequence of three shots, same woman, same place, same lighting throughout.
Shot 1: Wide shot, night, light rain on a narrow Paris street with glowing café windows. A woman in a long beige trench coat walks toward the camera under a transparent umbrella, wet cobblestones reflecting warm yellow streetlights.
Cut to Shot 2: Close-up on her face under the umbrella, raindrops on the plastic, warm café light on her cheek, she smiles softly.
Cut to Shot 3: Medium shot from inside the café through the rainy window, she pushes the door open and steps in, warm light spilling onto the wet pavement.
Calm, melancholic, romantic mood.

Vários planos num clip, ou uma sequência? Servem propósitos diferentes:

Prolongar um clip

Um clip pode ser prolongado: o plano seguinte continua o movimento do anterior, sem paragem na junção. É guiado por aproximadamente o último segundo do clip anterior, não por um único fotograma estático. Adiciona ao POST /videos:

O plano prolongado mantém a resolução do clip anterior: width e height são ignorados com extend_job_id, e com extend_video o tamanho é lido do ficheiro que envias. Contém apenas os novos fotogramas, por isso os planos encadeados formam um vídeo contínuo. Mantém a taxa de fotogramas do clip anterior: omite fps (herda-a) ou indica a mesma; uma diferente é recusada (extend_fps_mismatch). length é a nova duração do plano (121 = mais 5 s a 24 fps), e é exata: a duração automática não se aplica a uma extensão. Uma extensão custa o preço de um clip.

Limites: sem imagem final nem imagens-chave ao mesmo tempo, exceto com coerência reforçada.

O som continua na junção. Com audio: true, quando o final do clip anterior tem uma faixa sonora, o novo plano retoma esse som em vez de criar um novo. Com extend_job_id, o final cortado mantém o som do clip; com extend_video, envia o final com o seu som. Sem faixa sonora nesse final, em coerência reforçada e em Ultra, o som começa do zero com o plano: mantém o mesmo ambiente em cada prompt, para que a junção seja o menos percetível possível.

Prolonga um clip pouco depois de terminar. Mais tarde já não nos está disponível (clip_unavailable), e envias o seu final tu próprio em extend_video.

Prolongar um plano Ultra, para a frente ou para trás

Um plano renderizado em Ultra ao segundo também se prolonga em Ultra, para a frente ou para trás; qualquer outro clip prolonga-se como acima. Envia POST /videos com "quality": "max" e:

• A renderização contém apenas a parte nova, com a duração de um clip Ultra (length / fps, 5 s com a duração automática). Adota a resolução do plano (width e height são ignorados) e liga-se ao seu último fotograma (forward) ou ao primeiro (backward).
• Sem imagem inicial, referências (multiref), movimento nem coerência reforçada. backward não entra numa sequência, que arruma os seus planos uns a seguir aos outros.
• Preço: a parte nova ao preço do Ultra ao segundo, mais, por segundo do plano prolongado, 2 créditos em 480p, 5 em 720p e 13 em 1080p (ultra.extend_per_second em GET /pricing). Esses segundos são arredondados ao segundo superior (com uma precisão de 0,1 s) e contam a 24 fotogramas por segundo: um plano com cadência mais alta conta proporcionalmente (2 s a 60 fps contam como 5 s). POST /videos/quote com os mesmos campos dá extend_seconds e o preço exato.
• Um plano com mais de 24 horas: envia o seu ficheiro original, tal como entregue por GET /videos/{jobId}/file. POST /extensions com { "size": <bytes> } devolve upload_id, upload_url, headers e expires_in (900 s); envia o ficheiro com PUT upload_url e exatamente esses headers, depois passa extend_upload_id no prazo de 2 horas. Um envio serve para uma renderização: um MP4 de 4 a 30 s, no máximo 60 MB e 1080p. Antes da renderização, cada vídeo enviado ao modo Ultra (um movimento ou um vídeo a prolongar) é verificado, e nada é debitado se for recusado (400 input_video_out_of_limits): 24 a 60 imagens por segundo, uma proporção largura/altura de 0,4 a 2,5 e, por renderização, no máximo 30 s e 10 ficheiros para os vídeos e os sons de referência em conjunto. Com um rosto realista, um ficheiro recodificado ou editado é recusado (400 engine_refused): só o original passa. Um vídeo que não foi renderizado no modo Ultra (o render de outro modo, por exemplo) não é prolongado em Ultra quando mostra um rosto realista (400 extension_real_face, nada é debitado): prolonga-o no modo Qualidade, ou refaz o plano em Ultra.

Coerência reforçada

Com "consistency": "enhanced", o clip é renderizado por um modo que mantém movimento, rostos e fundo mais estáveis ao longo do tempo. Vai até 721 fotogramas por plano, ou seja 30 s a 24 fps e 24 s a 30 (length, comprimento fixo) e destina-se sobretudo a vídeos longos:

• Primeiro plano: um clip normal (prompt, imagem inicial, keyframes, end_image), até 721 fotogramas.
• Extensão: extend_job_id (ou extend_video) como em Prolongar um clip, com o mesmo consistency. length continua a ser a nova duração (até 721, ou seja mais 30 s a 24 fps). Uma extensão reforçada também aceita keyframes, cujo at conta a partir do primeiro novo fotograma, e uma imagem final end_image, definida no último fotograma do plano: por exemplo a imagem inicial do primeiro plano, para que um vídeo longo faça um loop.

Apenas no modo Qualidade (mode ltx25, sem quality: "max"), até 1080p, não disponível em Multi-Ref (400 consistency_mode). Preço: a taxa fixa do formato (480p sem som: 5 créditos) até 481 novos fotogramas (20 s a 24 fps), duplicado além disso (vê a tabela de preços acima). Taxas de fotogramas: 24, 30, 50 ou 60. Acima de 30, o comprimento é fixo (fps_requires_fixed_duration caso contrário); 50 dá um ligeiro câmara lenta (vê fps). A renderização demora mais do que um clip normal, e o início pode aguardar uma placa gráfica maior (planos longos). Uma sequência mantém o mesmo consistency para todos os seus planos. Tamanho entregue: o mesmo que em Qualidade a 720p e 1080p; a 480p, o lado curto sai a 448 (448 x 832, 832 x 448, 448 x 448), pois este modo trabalha em múltiplos de 64.

Alguns prompts ainda não são suportados. Para eles, um único plano de 20 s ou menos (15 s com um end_image, a comprimento fixo) é renderizado em consistência normal, ao mesmo preço. Além disso (length acima de 481 com duration_auto: false, ou acima de 361 com um end_image), numa extensão ou numa sequência, o pedido é recusado com 400 consistency_explicit: encurta o plano ou pede consistency: "standard".

Vídeo longo (sequências)

Um clip dura no máximo 481 fotogramas, ou seja 20 s a 24 fps (721 com coerência reforçada, 30 s a 24 fps). Para durações maiores, uma sequência regista cada plano assim que a sua renderização termina, e depois junta-os num único MP4 sem recodificação. Um minuto, por exemplo, são 3 planos de 20 s, ou 2 planos de 30 s em coerência reforçada, a 24 fps.

1. POST /sequences abre uma sequência e responde com { "sequence_id": "seq_...", ... }.
2. POST /videos com "sequence_id": "seq_..." para cada plano: o primeiro como habitualmente, os seguintes com extend_job_id definido para o plano anterior. Cada plano é registado na sequência, por ordem de submissão, assim que GET /videos/{jobId} o vê como terminado.
3. POST /sequences/{id}/export quando o último plano terminar. Responde com seconds, resolution e file_url.
4. GET /sequences/{id}/file: o vídeo montado (MP4).

Em paralelo: GET /sequences/{id} dá o estado (planos registados ou ainda esperados), POST /sequences/{id}/clips com { "job_id": "..." } regista uma renderização manualmente, e DELETE /sequences/{id} elimina a sequência de imediato.

Regras. Todos os planos têm a mesma resolução (as extensões mantêm-na) e a mesma escolha de som, todos com som ou todos silenciosos, o mesmo consistency e a mesma taxa de fotogramas (fps): o primeiro plano define-as, e um plano diferente é recusado (409 consistency_mismatch, 409 sequence_fps_mismatch; 422 encoding_mismatch para um plano registado manualmente). Um plano sem fps herda a taxa da sequência. No máximo 30 planos por sequência e 5 sequências em curso por licença.

O que guardamos e por quanto tempo. Os planos de uma sequência em curso são apagados 30 minutos após o último ter sido adicionado, e o vídeo montado 24 horas após a exportação. Depois tudo desaparece.

Exportar a pasta do projeto

Uma pasta de projeto reúne num ZIP tudo o que é preciso para retomar um vídeo noutro sítio ou automatizá-lo: os planos, as suas referências, a montagem e um manifesto que permite renderizar cada plano de novo. É gratuita: nada é renderizado.

• POST /videos/{jobId}/export: um render de POST /videos (plano isolado, Multi-Ref, extensão).
• POST /sequences/{id}/project: todos os planos de uma sequência, seguidos.
• Corpo opcional, as mesmas escolhas da janela de exportação da app:
  • include_media (true por omissão): os vídeos dos planos e os respetivos originais assinados. false: nenhum vídeo (nem clip, nem original, nem filme); os planos guardam o texto, as definições e as referências ("state": "expired") e o manifesto traz videos_included: false.
  • include_references (true por omissão): as vistas das personagens e as imagens dos elementos, em references/. false: nenhuma é copiada; os nomes, @menções, id e impressões digitais ficam no manifesto (references_included: false).
  • exclude_references: as referências a não copiar, uma a uma, por id (character_id, subject_id), nome ou @menção, por exemplo ["@Parc", "chr_..."] (200 no máximo). O manifesto traz references_included: "partial" e "included": false em cada excluída (false se forem todas). Uma entrada que não designa nenhuma referência da exportação: 400 unknown_reference.
  • include_film (só sequência, false por omissão): o filme de uma sequência já montada; exige include_media (senão 400 invalid_export_options, tal como uma opção que não é booleana ou um exclude_references que não é uma lista de textos).
  • manifest_only: true: só o manifesto, sem ZIP.

A resposta é { "manifest": { ... }, "file_url": "...", "export_id": "exp_...", "expires_at": "...", "bytes": n }, e GET /exports/{id}/file descarrega o ZIP. Uma exportação de cada vez por licença (409 export_in_progress), 2 GB no máximo (413 export_too_large: exporta os planos um a um).

O que guardamos e por quanto tempo. Para cada POST /videos aceite, o servidor guarda uma ficha do render sem nenhuma imagem nem vídeo: o texto, as definições, os identificadores (uma imagem enviada em base64 só deixa a sua impressão digital). É apagada 24 horas após o envio; depois disso, a exportação responde 404 unknown_export. O ZIP é apagado 45 minutos após o seu primeiro download, 2 horas após a sua criação no máximo. Um plano que o servidor já não tem sai com "state": "expired", sem o ficheiro mas com o texto, as definições e as referências: um agente pode renderizá-lo de novo com api_request.

Sequência. A montagem apaga os planos um a um. Para teres os planos e o filme, exporta o projeto antes de montar, depois monta e exporta de novo com { "include_film": true }: o filme junta-se, e os planos saem então como expired.

Modo Ultra

O modo Ultra é a renderização de vídeo mais fina. Adiciona "quality": "max" a POST /videos (com mode ltx25, o valor predefinido). É faturado ao segundo, ou a preço fixo com um LoRA ou numa extensão de um clip que não foi renderizado ao segundo; prolongar um plano Ultra, para a frente ou para trás, é faturado ao segundo. POST /videos/quote dá o preço exato do teu pedido.

Ao segundo

O clip é faturado ao segundo conforme a sua resolução, som incluído:

• Duração: de 4 a 30 s a 24 imagens por segundo, conhecida antes da renderização: 5 s em duração automática (duration_auto, por predefinição), caso contrário length / fps (24 se fps faltar), arredondada ao segundo.
• Formato: o pedido, na proporção mais próxima; o 480p é renderizado em 480p. Acima de 1080p: resolution_outside_ultra.
• Imagem inicial (image): possível. O motor pode recusar um texto ou uma imagem no envio: 400 engine_refused, com o motivo em detail e o código em code; nada é debitado.
• Sem semente: seed é ignorada e a resposta não a indica.
• Cancelamento: livre enquanto a renderização espera a sua vez; depois de entrar em cálculo, 409 render_in_progress, e o clip é entregue e faturado.
• Sem imagem final, sem imagens-chave e sem coerência reforçada em Ultra.

A preço fixo

Com um LoRA ou numa extensão de um clip que não foi renderizado ao segundo, o Ultra é renderizado com o modelo de vídeo completo, a preço fixo:

O preço é fixo por formato: o som e a duração não mudam nada. O Ultra começa a 720p: um pedido 480p é renderizado, e faturado, em 720p. POST /videos/quote dá o preço exato. 1080p (1920 x 1088) é o máximo, em todos os modos: o 4K deixou de ser oferecido. Um tamanho maior é recusado (ultra_4k_unavailable com quality: "max", resolution_above_quality sem ele).

• Duração: no máximo 481 fotogramas, como qualquer clip (20 s a 24 fps, 16 s a 30, 8 s a 60). As extensões e os vídeos longos também funcionam em Ultra. Uma extensão mantém o tamanho do clip que continua, e abaixo de 720p é faturada ao preço de 720p.
• Tempo: vários minutos para um clip de 5 s, mais para um clip de 20 s. O início pode aguardar que uma placa gráfica grande fique disponível.
• Sem transição (end_image) em Ultra (ultra_incompatible).
• Sem imagens-chave (keyframes) em Ultra (keyframes_mode).
• Um LoRA da personagem da tua conta aplica-se em Ultra como no modo normal.

Multi-Ref Vídeo

Um clip onde 1 a 4 personagens (até 12 em Ultra) atuam, cada uma reconhecível, num cenário opcional, com objetos, animais e um cenário guardados quando precisares. As personagens vêm de GET /characters: criadas a partir de uma foto através da API, ou na app. Os objetos, animais e cenários vêm de GET /subjects. Adiciona o objeto multiref ao POST /videos (permissão videos) e chama cada personagem por @Name no prompt:

{
  "prompt": "@Lea walks toward @Tom in a sunny kitchen and hands him a cup. Sound: footsteps, soft music.",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Lea", "description": "a 28 year old woman with long red hair" },
      { "character_id": "chr_21bc...", "name": "Tom", "description": "a 30 year old man", "strength": 1.2 }
    ],
    "background_b64": "<optional: an image of the location>",
    "background_description": "a sunny kitchen"
  },
  "width": 1088, "height": 1920,
  "audio": true
}

• Prompt em inglês, um parágrafo no presente; Sound: para o som, diálogos entre aspas, exactly 2 people e onde cada um está quando ajuda, sem negações. Uma criatura é descrita pelo que é. Um @Name que não corresponde a nenhuma personagem é recusado (unknown_mention).
• Formatos (width x height): retrato 480 x 832, 720 x 1280, 1088 x 1920; paisagem 832 x 480, 1280 x 720, 1920 x 1088; quadrado 480 x 480, 720 x 720, 1088 x 1088. Sem 4K; 480p apenas em Qualidade.
• Modos: Qualidade (o predefinido), ou Ultra (quality: "max"). Sem extensão nem transição.
• Duração: automática (duration_auto, o predefinido), ou fixa com duration_auto: false e length 121 (5 s), 241 (10 s) ou 481 (20 s) a 24 fps; a outra taxa, as mesmas durações contadas em fotogramas, no máximo 481 (a 30: 145, 297, 481; a 60: 297, 481).
• Taxa de fotogramas: fps 24, 30 (o predefinido) ou 60, como em qualquer clip; length conta fotogramas a esta taxa, no máximo 481 (16 s a 30, 8 s a 60).
• Preço: o preço de um clip. Em Qualidade, o preço fixo do formato na tabela acima, duplicado com som; 480p sem som mantém-se a 5 créditos (o preço reduzido de Qualidade não se aplica ao Multi-Ref). POST /videos/quote com "multiref": true dá o preço exato.
• O servidor adapta as vistas ao formato exato do vídeo: envia as personagens tal como estão. Uma personagem que tem apenas uma vista é renderizada, com warnings limited_likeness na resposta: a semelhança é limitada.
• Vozes de perfil: com som, characters[0] e characters[1] falam por predefinição com a voz do seu perfil quando está online (has_voice); voice generated deixa o modelo fazer uma. A resposta dá a voz de cada uma em voices (character_id, voice: character, custom ou generated).
• Vozes das personagens (voice_b64): o modelo faz a personagem falar com essa voz, incluindo os lábios; o servidor usa os primeiros 5 segundos. No máximo duas vozes, em characters[0] e characters[1] (o motor suporta 2 vozes). Ordena characters como o diálogo: characters[0] fala primeiro, characters[1] responde. Requer som ("audio": true), caso contrário voice_requires_audio; uma voz noutra personagem: voice_slot; um ficheiro ilegível: unsupported_audio_format; acima de 4 MB: audio_too_large. Apenas os primeiros 5 segundos são usados: envia um excerto curto. O corpo do pedido completo não deve ultrapassar 30 MB (acima disso, um 413 sem corpo JSON). Sem custo adicional.
• A consulta, o download e o cancelamento são os de qualquer vídeo (vê Consultar, descarregar, cancelar, acima).

Objetos, animais e cenários guardados. Mais dois campos de multiref colocam os sujeitos que guardaste a partir das tuas próprias imagens:

name tem como predefinição a primeira palavra do nome do sujeito, e cada @Name no prompt é correspondido como o de uma personagem. Um cenário passado em subjects, ou um objeto passado como location, é recusado (invalid_subject_type). O preço não muda: é o preço de um clip. Um sujeito é usado com as suas 5 primeiras imagens (todas em Ultra, 6 no máximo).

"multiref": {
  "characters": [{ "character_id": "chr_8f3a...", "name": "Lea" }],
  "subjects": [{ "subject_id": "sub_1c2d...", "name": "Rex" }],
  "location": { "subject_id": "sub_9e8f...", "name": "Loft" }
},
"prompt": "@Lea throws a ball to @Rex across @Loft. Sound: barking, laughter."

Em Ultra, um clip Multi-Ref segue as regras do Ultra faturado ao segundo: mesmo preço por segundo, som incluído, de 4 a 30 s a 24 imagens por segundo (5 s em duração automática), de 480p a 1080p, sem semente.

• Cada personagem parte com a sua character sheet (ou, sem ela, com todas as suas imagens), e o servidor junta tudo numa única imagem; cada objeto, animal ou cenário com todas as suas imagens (6 no máximo).
• A primeira renderização de uma personagem prepara essa imagem, umas dezenas de segundos a mais: o seu jobId começa então por sdp- e acompanha-se como os outros.
• Sem voz: voice_b64 e a voz da ficha são ignoradas (warnings voice_ignored), e strength não tem efeito.
• O motor pode recusar uma imagem de referência (um rosto real, por exemplo): a renderização termina em failed com o motivo, e nada é debitado.

Estilos, roupas e movimento. Só em Ultra (quality: "max"), mais três campos de multiref; noutro modo, o pedido é recusado (multiref_ultra_only), nunca renderizado sem eles.

• No máximo 30 imagens em Ultra, entre personagens, sujeitos, estilos, roupas e cenário (multiref_too_many_images), com 12 personagens no máximo (multiref_characters_required acima disso). Recomendam-se 8: de 9 a 12, o render é processado com warnings many_characters, porque algumas podem faltar ou misturar-se. Um estilo fora de styles, ou uma roupa fora de outfits, é recusado (invalid_subject_type).
• Preço do movimento: 3 créditos por segundo do vídeo de movimento (arredondado ao segundo superior), além do render, lido em GET /pricing (ultra.motion_per_second); POST /videos/quote com o mesmo multiref.motion dá motion_seconds e o preço exato.
• Envio direto, para um vídeo de movimento pesado: POST /motions com { "size": <bytes> } (no máximo 20 MB) devolve motion_id, upload_url, headers e expires_in (900 s); envia o ficheiro com PUT upload_url e exatamente esses headers, depois passa multiref.motion.motion_id a POST /videos no prazo de 2 horas. Um motion_id serve para um render.

"quality": "max",
"multiref": {
  "characters": [{ "character_id": "chr_8f3a...", "name": "Lea" }],
  "styles": [{ "subject_id": "sub_a1b2..." }],
  "outfits": [{ "subject_id": "sub_c3d4...", "name": "RedGown", "worn_by": "Lea" }],
  "motion": { "motion_id": "4f0c2a9b1d7e6a35", "description": "a low tracking shot from the side" }
},
"prompt": "@Lea walks along a seaside promenade at sunset."

Os códigos de erro dos estilos, das roupas e do movimento estão em Limites e erros.

Com o servidor MCP, o agente faz tudo isto com tendre_multiref_video: pede a cena e nomeia as personagens, objetos, animais e o cenário (subjects, location_id).

Face swap

A pessoa filmada no teu próprio vídeo torna-se uma das tuas personagens: rosto, cabelo, corpo e roupa (ou só a cabeça, ver part), mantendo os seus gestos, os lábios e o cenário, e a voz, salvo se a personagem tiver a sua (ver voice). É o Face swap da app, numa passagem de no máximo 20 s: uma personagem, sem encadeamento e sem transição. O pedido é POST /faceswap (permissão videos):

{
  "video_b64": "<the video in base64: MP4, MOV, WebM or MKV, 20 MB at most>",
  "character_id": "chr_8f3a...",
  "start": 2,
  "duration": 6,
  "scene": "@Lea wears a long red coat.",
  "zone": "normal",
  "likeness": 1
}

Vídeo e voz juntos: no máximo 22 MB, para que o corpo do pedido não ultrapasse 30 MB (acima disso, um 413 sem corpo JSON).

• O servidor prepara tudo. Corta a passagem, ajusta-a para a taxa de fotogramas de trabalho (30 fps para uma fonte a 29 fps ou mais, incluindo 50 e 60, e 24 abaixo) e para o formato de trabalho (múltiplos de 128, lado curto de 768, a proporção mais próxima do teu vídeo), e adapta as vistas da personagem a esse formato.
• O que recebes de volta é o vídeo da passagem no formato de trabalho, cerca de um megapixel (768 x 1408 para um vídeo vertical, por exemplo), com as proporções do teu vídeo dentro de 5%. Resolução total e várias personagens em sequência são específicos da app de ambiente de trabalho tendre.AI: ela cola a personagem de volta no vídeo original com a sua resolução total, e encadeia várias personagens.
• Preço: 6 créditos por segundo da passagem preparada (seconds na resposta), arredondado para cima ao crédito seguinte. A resposta dá jobId, seed, cost e a passagem preparada (width, height, length, fps, seconds, audio, voice, views, part). Uma personagem que tem apenas uma vista é renderizada, com warnings limited_likeness.
• Sem cotação: nem POST /videos/quote nem o tendre_quote do MCP conhecem o Face swap. Para calcular o preço antes de submeter, lê grid.body_swap em GET /pricing: segundos da passagem x per_block_720p (o preço de um bloco) / block_seconds (a duração de um bloco), arredondado para cima ao crédito seguinte.
• Algumas cenas são renderizadas a partir dos três retratos da personagem recortados à cabeça (heads_only na resposta), e o traje das suas vistas já não é imposto: a cena decide.
• Um Face swap conta como uma utilização da personagem e adia a sua eliminação, tal como o Multi-Ref.
• A consulta, o download e o cancelamento são os de qualquer vídeo (vê Consultar, descarregar, cancelar, acima): GET /videos/{jobId}, GET /videos/{jobId}/file, POST /videos/{jobId}/cancel.
• Erros próprios: video_required, video_too_large, unreadable_video, invalid_start, passage_too_short, invalid_duration, invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part, invalid_voice_choice, character_required, unknown_character, audio_too_large (uma voz acima de 2 MB), face_swap_too_large (a passagem ainda está demasiado pesada depois de preparada: encurta duration), server_busy (dois vídeos já estão a ser preparados: tenta de novo após Retry-After, 20 s), face_swap_unavailable e face_swap_price_missing (Face swap encerrado, ou sem preço: tenta mais tarde). O que cada um significa: Limites e erros.
• O teu vídeo passa pelos nossos servidores enquanto é preparado, depois vai para a placa gráfica que o renderiza, como qualquer imagem de origem.

Usa apenas vídeos de pessoas que deram o seu consentimento: é uma regra dos termos de utilização.

Com o servidor MCP, o agente faz tudo isto com tendre_face_swap.