Clipwright

API do Clipwright

Uma API HTTP que transforma um roteiro em um vídeo UGC com sincronização labial ou um roteiro ou briefing curto em um vídeo sem rosto: narração sobre um clipe animado de abertura e cenas com imagens. Ela foi criada para ser controlada por um agente: cada chamada é uma única solicitação JSON, cada recusa informa o que fazer em seguida e nada é publicado em lugar algum. Cada palavra desta página também está em um arquivo Markdown em https://clipwright.io/docs.md e em um contrato curto para agentes em https://clipwright.io/llms.txt destinado a agentes que leem texto. O arquivo OpenAPI 3.1 em https://api.clipwright.io/openapi.json é o contrato REST legível por máquina, criado a partir dos esquemas que a API valida.

Autenticação

Todas as chamadas são feitas para https://api.clipwright.io e incluem a chave em um cabeçalho:

Authorization: Bearer cw_your_key_here

• As chaves começam com cw_ e são exibidas uma única vez, quando são emitidas. Guardamos apenas um resumo criptográfico, então uma chave perdida é substituída, nunca recuperada.
• Emita e revogue chaves em https://app.clipwright.io/api-keys no painel. A revogação entra em vigor na próxima solicitação.
• @clipwright/cli e @clipwright/mcp-server leem a chave da variável de ambiente CLIPWRIGHT_API_KEY; @clipwright/sdk recebe a chave como argumento.
• Uma chamada sem chave ou com uma chave revogada é recusada com 401 antes de qualquer cobrança.

03

Quanto custa

• make_ugc a partir de um roteiro simples: 10 créditos por segundo de vídeo finalizado, arredondados para o segundo inteiro seguinte, com mínimo de 50 em um vídeo entregue por nós.
• make_ugc com segmentos ou inserções: 9 créditos por segundo em que um rosto aparece na tela (22 em uma tomada renderizada no OmniHuman), mais 1 por segundo de vídeo e 400 por cada imagem de chamada de avatar ao vivo, com mínimo de 50 créditos em um vídeo entregue por nós. Um rosto coberto por uma inserção, sobreposição, janela ou modelo ainda conta, e uma execução que não entrega nenhum arquivo não custa nada. O tempo de rosto é somado ao longo de todo o vídeo e arredondado para cima uma única vez, não por segmento. Esses campos exigem qualificação para vídeos longos; quando ela está desativada, são recusados pelo nome antes de qualquer cobrança.
• create_actor com qualidade medium: 4 créditos pelo retrato (nenhum quando a imagem é sua e é enviada em portrait; 4 por uma visualização de um ator existente feita com from_actor_id) e 8 por cada formato adicional.
• create_actor com qualidade high: 45 créditos pelo retrato (nenhum quando a imagem é sua e é enviada em portrait; 12 por uma visualização de um ator existente feita com from_actor_id) e 18 por cada formato adicional.
• make_faceless: 7 créditos por imagem gerada, 49 pelo clipe de abertura e 1 por segundo do vídeo entregue, com mínimo de 50. O orçamento para duration_seconds é o máximo que você paga: 212 em 30 segundos, 356 em 90. Suas próprias imagens não são cobradas, e as legendas não alteram o preço.
• Os créditos são comprados em pacotes: 1000 créditos por $10.00, 2750 créditos por $25.00, 6000 créditos por $50.00. Um pacote por pagamento, sem assinatura.

Consulte antes de gastar: o endpoint de orçamento de cada habilidade não cobra nada. O valor da resposta varia conforme a habilidade.

• make_ugc: o orçamento é uma estimativa baseada nas palavras do roteiro. A cobrança segue o que foi medido no vídeo finalizado — sua duração no medidor de roteiro simples, seus segundos de rosto no medidor de rosto —, então o valor pode ficar acima ou abaixo do orçamento.
• create_actor: o orçamento calcula o preço de todos os formatos solicitados, que é o máximo que você pode pagar. Você paga pelo retrato e pelas variantes efetivamente publicadas; um formato que não foi gerado é indicado em warnings[] e não custa nada.
• make_faceless: o orçamento calcula o preço de duration_seconds solicitado, que é o máximo que você pode pagar. O vídeo dura o tempo necessário para a narração, no mínimo 25 segundos (um vídeo explicativo, apenas a narração) e, em geral, no máximo um quarto a mais que essa duração e 90 segundos; uma narração mais longa vai até o fim. Você paga pela duração efetivamente entregue, nunca mais do que o orçamento.

O custo de uma execução malsucedida também varia conforme a habilidade:

• make_ugc a partir de um roteiro simples: uma execução que falha depois que o vídeo foi solicitado é cobrada. Uma que falha antes disso não custa nada, assim como uma que interrompemos, perdemos ou recusamos. No medidor de rosto, nenhuma falha é cobrada.
• create_actor: uma execução malsucedida não custa nada, pois nenhum ator chegou até você.
• make_faceless: uma execução malsucedida não custa nada, inclusive quando a interrompemos porque uma etapa não passou pelas nossas verificações. Uma execução retida para análise mantém os créditos reservados até ser resolvida.

04

Preços de edição

Uma revisão de um vídeo sem rosto é uma nova execução feita a partir de um documento editado: POST /v1/runs/{id}/revisions/quote calcula o preço sem cobrar nada; POST /v1/runs/{id}/revisions inicia a execução.

• Uma nova imagem: 7 créditos.
• Um novo clipe de abertura: 49 créditos.
• Uma nova imagem estática de abertura e seu clipe: 56 créditos.
• A renderização de uma revisão que gera qualquer conteúdo: 13 créditos, uma vez por revisão.
• A renderização de uma revisão que não gera nada (uma alteração de tempo, uma exclusão ou um upload seu): 13 créditos.
• Depois que as edições pagas forem habilitadas, um original poderá ser editado mediante pagamento por 364 dias após sua conclusão.
• Revisões simultâneas de um mesmo original: no máximo 1. Com falha ou inacabadas: no máximo 3.
• Uma revisão entregue é cobrada pelo total orçado; uma que falha não custa nada.
• Enquanto as edições pagas estiverem desabilitadas, as duas rotas de revisão respondem com editing_disabled e não cobram nada.

05

Preços de candidatos de tomada

Um candidato de tomada é uma imagem ou clipe criado para uma tomada de um vídeo sem rosto, para manter ou descartar em uma revisão: POST /v1/runs/{id}/candidates/quote calcula o preço sem cobrar nada; POST /v1/runs/{id}/candidates cria o candidato.

• Um candidato de imagem: 7 créditos.
• Um candidato de clipe de abertura: 49 créditos.
• Um candidato de imagem estática de abertura e seu clipe: 56 créditos.
• Candidatos de tomada simultâneos de um mesmo original: no máximo 1. Com falha ou inacabados: no máximo 3. As revisões são contabilizadas separadamente.
• Um candidato entregue é cobrado por sua unidade, seja mantido ou descartado; um que falha não custa nada.
• Enquanto os candidatos de tomada estiverem desabilitados, as três rotas de candidatos respondem com editing_disabled e não cobram nada.

06

Endpoints

Endpoint	Custa créditos	O que faz
POST /v1/skills/make_faceless/quote	não	Calcula o preço de uma chamada make_faceless com esta entrada. Não cobra nada.
POST /v1/skills/make_faceless/run	sim	Inicia uma execução de vídeo sem rosto e responde imediatamente com um run_id. Consulte a execução para obter o resultado.
GET /health	não	Verifica se a própria API está ativa. Responde sem uma chave.
GET /	não	Informa o nome do serviço e aponta para este documento. Responde sem uma chave.
GET /robots.txt	não	Instrui os rastreadores a não indexar o host da API. Responde sem uma chave.
GET /openapi.json	não	A descrição OpenAPI 3.1 desta API, criada com os mesmos esquemas usados para validar as chamadas da API. Responde sem uma chave.
GET /v1/voices	não	Vozes que você pode especificar em voice ou voice_id para make_ugc; skill=make_faceless lista as vozes de narração de make_faceless.
GET /v1/template-sounds	não	Os sons reproduzidos pelos modelos make_ugc, por batida: onde cada batida é reproduzida, seu padrão e todos os nomes aceitos por template_sounds. Grátis.
GET /v1/moves	não	O catálogo de movimentos que podem ser aplicados às linhas de um roteiro como moves de make_ugc, make_faceless e uma recriação de referência: o que cada um faz para o espectador, as linhas a que se aplica e os créditos por uso, com filtros e paginação; names fornece as linhas completas. Grátis.
GET /v1/account	não	Saldo, dívida e créditos retidos da conta associada à chave, além das nossas respostas às solicitações de suporte e aos comentários enviados por ela.
POST /v1/skills/make_ugc/quote	não	Calcula o preço de uma chamada make_ugc com esta entrada. Não cobra nada.
GET /v1/runs/{id}	não	Estado de uma execução de qualquer skill, seus avisos e a URL do vídeo.
GET /v1/runs/{id}/shots	não	Os planos de uma execução: intervalo, falas, descrição e prévia de cada plano, e se a execução pode ser editada.
GET /v1/runs/{id}/edit	não	O rascunho salvo de uma edição de uma execução, com sua versão. A versão 0 é uma execução sem rascunho: seu documento não altera nada.
POST /v1/runs/{id}/edit	não	Salva o rascunho de uma edição com base na versão em que foi lido. Não cobra nem renderiza nada.
POST /v1/runs/{id}/revisions/quote	não	Calcula o preço de uma revisão de uma execução sem rosto: o que o documento ou a lista de alterações nos planos gera e quanto custa. Não cobra nada. Uma revisão entregue é cobrada pelo total cotado; uma que falha não é cobrada. Enquanto as edições pagas estiverem desativadas, responde editing_disabled.
POST /v1/runs/{id}/revisions	sim	Inicia uma revisão, uma nova execução sem rosto criada a partir do documento, e retém os créditos cotados. A mesma Idempotency-Key com a mesma solicitação retorna a primeira revisão; outra chave cria outra revisão, cobrada novamente. Uma revisão entregue é cobrada pelo total cotado; uma que falha não é cobrada. Enquanto as edições pagas estiverem desativadas, responde editing_disabled e não cobra nada.
POST /v1/runs/{id}/candidates/quote	não	Calcula o preço de um plano candidato de uma execução sem rosto: uma imagem ou um clipe criado para um plano, que pode ser mantido ou descartado. Não cobra nada. Um candidato entregue custa uma unidade, seja mantido ou descartado; um que falha não é cobrado. Enquanto os planos candidatos estiverem desativados, responde editing_disabled.
POST /v1/runs/{id}/candidates	sim	Inicia um plano candidato e retém o preço de uma unidade. Um candidato entregue custa uma unidade, seja mantido ou descartado; um que falha não é cobrado. A mesma Idempotency-Key com a mesma solicitação e take retorna o primeiro candidato; take + 1 cria outro, cobrado novamente. Enquanto os planos candidatos estiverem desativados, responde editing_disabled e não cobra nada.
GET /v1/runs/{id}/candidates	não	Os planos candidatos da família de uma execução sem rosto, do mais antigo ao mais recente, cada um com seu estado, sua cobrança e uma prévia quando estiver pronta. Enquanto os planos candidatos estiverem desativados, responde editing_disabled.
DELETE /v1/runs/{id}/media	não	Exclui os arquivos de uma execução concluída: a partir de agora, nenhum link para eles será fornecido, e eles serão apagados do armazenamento após 7 dias. A execução e sua cobrança permanecem. Recusado com run_media_in_use enquanto outra execução não concluída os estiver usando. Grátis.
POST /v1/skills/make_ugc/run	sim	Inicia uma execução de vídeo e responde imediatamente com um run_id. Consulte a execução para obter o resultado.
GET /v1/public/skills	não	Catálogo de skills e suas entradas, sem uma chave.
GET /v1/public/prices	não	O preço de cada ação em créditos: um número fixo por unidade ou uma fórmula em que o preço depende da entrada; a cotação informa o valor exato. Grátis, sem uma chave.
GET /v1/actors	não	Atores salvos na conta, com o id aceito por make_ugc.
GET /v1/public/actor-previews/{actor_id}/{version}/{file}	não	A imagem PNG de um ator da biblioteca, no link fornecido por list_actors e pelas cotações. Responde sem uma chave.
DELETE /v1/actors/{id}	não	Remove um ator salvo. Um ator usado por uma execução ativa é mantido.
GET /v1/actors/{id}/defaults	não	Lê a política padrão do ator salvo para pessoas em inserções.
POST /v1/actors/{id}/defaults	não	Define a política padrão do ator salvo para pessoas em inserções. Uma execução pode substituí-la.
GET /v1/brand-kit	não	Lê o design salvo da conta: cores, fontes, logotipo, cantos e movimento. Null quando nenhum design está salvo.
POST /v1/brand-kit	não	Salva o design da conta ou o limpa com null. Um vídeo que não especifica design nem template_theme usa esse design. Grátis.
POST /v1/brand/extract	não	Lê as cores, fontes, logotipo e cantos de um site público e os reúne em um design proposto com texto legível, para você confirmar. Grátis; conta para o limite de downloads de url por hora.
POST /v1/skills/create_actor/quote	não	Calcula o preço de uma chamada create_actor com esta entrada. Não cobra nada.
POST /v1/skills/create_actor/run	sim	Inicia uma execução de ator e responde imediatamente com um run_id. Consulte a execução para obter o resultado.
POST /v1/uploads	não	Recebe bytes de imagem e retorna uma URL https assinada, upload_id e content_digest (SHA-256 dos bytes originais). Use upload_id como asset_id de um workflow e copie content_digest diretamente; chamadas nativas de vídeo e ator usam url.
GET /v1/uploads	não	Seus uploads que uma revisão ainda pode usar, do mais recente ao mais antigo e um por imagem, cada um com upload_id, o content_digest original, uma URL recém-assinada e o momento em que deixa de ser utilizável. Grátis.
POST /v1/uploads/import	não	Baixa um PNG ou JPEG público em https (até 10 MB, 20 segundos, 3 redirecionamentos) e retorna o mesmo formato de upload. Endereços privados são recusados; 30 downloads por hora por conta. Grátis.
POST /v1/uploads/intents	não	Retorna uma URL PUT pré-assinada para um PNG ou JPEG local com o tipo, tamanho e sha256 declarados. O upload_id pode ser usado assim que o PUT for concluído; antes disso, as gerações respondem upload_not_finished. Grátis.
GET /v1/uploads/{id}	não	Um upload com uma URL recém-assinada e seu usable_until. Após um PUT pré-assinado, confirma o arquivo: upload_not_finished até que ele esteja disponível, upload_expired após 24 horas. Grátis.
DELETE /v1/uploads/{id}	não	Exclui um upload: a partir de agora, nenhuma chamada poderá usá-lo, e o arquivo será apagado do armazenamento após 7 dias, a menos que outro upload da mesma imagem seja mantido. Recusado com upload_in_use enquanto uma execução não concluída o estiver usando. Grátis.
POST /v1/assets	não	Salva uma imagem como recurso da conta, mantido até você excluí-lo: a partir de um run_id, upload_id, URL pública em https ou base64. Seu próprio material exige rights_confirmed: true ou analysis_only: true para uma referência mantida exclusivamente para analyze_reference, que nenhuma renderização ou geração pode usar. 2000 recursos e 1 GB por conta, 20 GB após a compra de créditos, 100 novos por dia. Grátis.
POST /v1/assets/bytes	não	Salva o PNG ou JPEG do corpo (até 10 MB) como recurso; role, name e rights_confirmed=true (ou analysis_only=true, exclusivamente para analyze_reference) são enviados na query. Grátis.
GET /v1/assets	não	Os recursos ativos da conta, do mais recente ao mais antigo, cada um com um link assinado por uma hora, e o uso dos limites; filtra por role e kind, com paginação por cursor. Grátis.
GET /v1/assets/{id}	não	Um recurso ativo com um link assinado por uma hora. Grátis.
POST /v1/assets/{id}	não	Renomeia um recurso ou altera seu role. Grátis.
DELETE /v1/assets/{id}	não	Exclui um recurso: ele sai da lista e deixa de estar disponível para gerações imediatamente, e uma limpeza diária remove seu arquivo após 7 dias. Grátis.
GET /v1/public/workflows	não	Lista os métodos de workflow públicos e informa se cada um está disponível no momento, sem planos de conta nem uma declaração de admissão da conta.
GET /v1/public/workflows/{id}	não	Lê as orientações e limitações de um método, e o que ele pode fazer no momento.
POST /v1/workflow-plans	não	Cria um rascunho de workflow imutável, pertencente à conta. Não cobra nada nem inicia uma renderização.
GET /v1/workflow-plans/{id}	não	Lê a revisão atual do workflow da conta e seu estado de prontidão.
POST /v1/workflow-plans/reference-remake	não	Compila um perfil de referência e o roteiro aprovado em um novo rascunho de recriação de referência; os avisos indicam o que o plano não reproduz. Não cobra nem gera nada e não inicia uma renderização.
POST /v1/workflow-plans/{id}/revisions	não	Salva um novo rascunho com base em base_version. Uma nova tentativa correspondente após perda da resposta retorna essa revisão.
POST /v1/workflow-plans/{id}/approve	não	Aprova uma revisão pronta e seu digest. Não cobra nada nem inicia uma renderização.
POST /v1/workflow-plans/{id}/quote	não	Calcula o preço de um workflow aprovado por meio da preparação nativa. A cotação expira após cinco minutos; nenhum crédito é reservado. O lançamento é o corpo pronto da solicitação de execução, com um idempotency_key novo.
POST /v1/workflow-plans/{id}/run	sim	Admite a solicitação nativa exata cotada uma vez, retornando um recibo e a Run nativa existente. Envie o launch da cotação sem alterações no corpo, com o cabeçalho Idempotency-Key igual a launch.idempotency_key; a mesma solicitação aceita reproduz sua execução.
GET /v1/generations/models	não	Os modelos aceitos por generate_image e generate_video, com seus modos medidos, proporções, resoluções, durações, tamanho de saída e créditos por imagem ou por segundo. Grátis. Enquanto as gerações estiverem desativadas, responde generations_disabled.
POST /v1/skills/generate_image/quote	não	Calcula o preço de uma imagem com esta solicitação: créditos, largura, altura e avisos. Não cobra nada.
POST /v1/skills/generate_image/run	sim	Inicia a geração de uma imagem e responde imediatamente com um run_id; o bloco generation da execução contém a imagem quando ela for entregue. Uma geração que falha não é cobrada. Enquanto as gerações estiverem desativadas, responde generations_disabled e não cobra nada.
POST /v1/skills/generate_video/quote	não	Calcula o preço de um clipe sem áudio com esta solicitação: créditos por segundo multiplicados pela duração, largura, altura e avisos. Não cobra nada.
POST /v1/skills/generate_video/run	sim	Inicia a geração de um clipe e responde imediatamente com um run_id; o bloco generation da execução contém o clipe quando ele for entregue. Uma geração que falha não é cobrada. Enquanto as gerações estiverem desativadas, responde generations_disabled e não cobra nada.
POST /v1/reference-analyses/quote	não	Calcula o preço de uma análise deste recurso ou link: 70 créditos, 10 com mode data ou 0 quando uma análise ativa nesse modo já responderia. Não cobra nada.
POST /v1/reference-analyses	sim	Inicia a análise de um recurso MP4, de até 120 s, para criar um perfil de referência (ou, com mode data, sua transcrição, gancho e uma folha de quadros) e responde imediatamente; o mesmo recurso no mesmo modo retorna a mesma análise gratuitamente. Retém 70 créditos (10 para data), cobrados quando a análise é concluída com sucesso; uma análise que falha não custa nada. 10 novas análises completas e 60 novas análises data por hora.
GET /v1/reference-analyses/{id}	não	Uma análise de referência: na fila, em análise, concluída com sucesso com reference_profile ou data e avisos, ou com falha e seu erro. Grátis.
POST /v1/creator-profiles/quote	não	Calcula o preço de um perfil de criador para este link: 20 créditos ou 0 quando um perfil do mesmo criador da última hora já responderia. Não cobra nada.
POST /v1/creator-profiles	sim	Inicia a análise do criador por trás de um perfil ou link de vídeo do Instagram ou TikTok: os 12 vídeos mais recentes, com visualizações, curtidas, comentários e compartilhamentos, a mediana de visualizações e o x de cada vídeo em relação a ela. Responde na hora; o mesmo criador dentro de uma hora retorna o mesmo perfil gratuitamente. Reserva 20 créditos, cobrados quando a análise é concluída com sucesso; contas privadas ou vazias, ou qualquer falha, não custam nada. 30 novos perfis por hora.
GET /v1/creator-profiles/{id}	não	Um perfil de criador: na fila, em análise, concluído com o perfil e avisos, ou com falha e seu erro. Gratuito.
DELETE /v1/creator-profiles/{id}	não	Exclui imediatamente um perfil de criador concluído; a execução que o criou e a cobrança permanecem. Recusado com run_not_finished enquanto estiver sendo criado. Gratuito.
POST /v1/trend-searches/quote	não	Calcula o preço de uma busca por tópico: 20 créditos, ou 0 quando uma busca pela mesma consulta na última hora já forneceria a resposta. Não cobra nada.
POST /v1/trend-searches	sim	Inicia uma busca por reels sobre um tópico, com TikTok e Instagram classificados em conjunto, a menos que a plataforma especifique um deles: até 10 reels por plataforma, um por criador, cada um com suas visualizações em relação à mediana do criador. Responde na hora; a mesma consulta dentro de uma hora retorna a mesma busca gratuitamente. Reserva 20 créditos, cobrados quando a busca é concluída com sucesso, inclusive quando os resultados incluem apenas uma plataforma (warnings[] indica a outra); nenhum reel encontrado ou qualquer falha não custa nada. 10 novas buscas por hora.
GET /v1/trend-searches/{id}	não	Uma busca por tópico: na fila, em andamento, concluída com os reels e avisos, ou com falha e seu erro. sort exibe os mesmos reels em outra ordem. Gratuito.
POST /v1/feedback	não	Conta para nós o que está faltando, confuso, errado ou lento, opcionalmente sobre uma execução desta conta; lemos todos os comentários. Gratuito. O mesmo tipo, texto e execução dentro de 24 horas retornam o mesmo feedback_id; 20 por hora.
Uma execução de qualquer skill é consultada no mesmo local, GET /v1/runs/{id}, e passa pelos seguintes estados: queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

GET /v1/runs/{id}?wait_seconds=N (no máximo 50) aguarda a resposta até a execução ser concluída com sucesso ou falhar, o tempo de espera terminar ou você se desconectar, portanto não é necessário aguardar entre as consultas. Uma execução ainda não concluída responde com seu estado atual.

07

Skills e suas entradas

make_ugc. Inicia a geração de um vídeo UGC com sincronização labial. O ator vem de actor_id (um ator salvo de list_actors) ou de image; caso contrário, o ator padrão é usado. O formato e a resolução seguem a solicitação e a fonte, com padrão de 1080x1920. As legendas são OPT-IN: pergunte primeiro ao usuário. Um campo que o renderizador ainda não respeita contém NOT HONORED YET em sua descrição.

Retorna um run_id imediatamente; consulte get_run com seus poll.arguments até o estado 'succeeded' (video_url) ou 'failed'. Uma execução 'failed' cujo vídeo ainda está sendo produzido pode voltar para 'queued' e ser concluída com sucesso mais tarde, conforme indicado em warnings[]. attempt=2,3,… inicia uma NOVA execução para a mesma entrada. Para criar um vídeo como um reel de referência, use analyze_reference e, em seguida, plan_reference_remake com seu analysis_id.

Campo	Obrigatório	O que significa
script	opcional	As palavras ditas pelo ator; obrigatório, a menos que segments forneça o texto falado. Segments e inserts ancorados em texto exigem qualificação para formato longo no servidor. Limites de script por modelo de fala: eleven_v3: 5000 caracteres; eleven_flash_v2_5: 10000 caracteres; eleven_turbo_v2_5: 10000 caracteres; eleven_v4: 5000 caracteres; gemini-3.8-flash-tts: 5000 caracteres. A contagem inclui espaços, tags de áudio e marcas de ênfase; emojis podem contar como dois caracteres. As tags de pausa são removidas do texto enviado para eleven_v4 e gemini-3.8-flash-tts e não são contabilizadas nesses modelos. Não há limite de contagem de palavras. A duração e o preço são estimativas até serem medidos. Acentuação tônica em russo: escreva a vogal tônica em maiúscula dentro de uma palavra em minúsculas ("потОм", "зАмок"); eleven_v4 e gemini-3.8-flash-tts a recebem como a marca de acento U+0301 ("пото́м"); uma marca digitada diretamente é mantida. Uma maiúscula no início de uma palavra continua maiúscula, e uma palavra com uma segunda maiúscula ou uma consoante maiúscula no meio (tudo em maiúsculas, "ВУЗы") permanece como está. Uma única vogal maiúscula dentro de uma palavra é sempre interpretada como acento tônico; portanto, escreva "Яндекс Еда", não "ЯндексЕда". Informe aos usuários que escrevem em russo que podem marcar o acento tônico dessa forma. eleven_flash_v2_5 e eleven_turbo_v2_5 custam menos, mas interpretam incorretamente as marcas de acento: as maiúsculas chegam a eles sem alterações.
segments	opcional	Segmentos ordenados de ator e imagem; exigem qualificação para formato longo no servidor, captions=false e 1080p. Mídia de imagem exige broll_policy=anyone explícito.
inserts	opcional	Inserts de imagem ou vídeo ancorados em texto sobre a narração completa, cada um cobrindo cover_words palavras faladas a partir da âncora; exigem qualificação para formato longo no servidor, 1080p e broll_policy=anyone explícito. As legendas são exibidas sobre os inserts.
overlays	opcional	Imagens ou vídeos ancorados em texto sobre o apresentador visível, cada um em uma posição ou local. No máximo 2 na tela ao mesmo tempo, em caixas que não se sobrepõem. As legendas se movem para o terço central ou inferior, fora do overlay, nunca sobre o rosto, e ficam ocultas enquanto nenhum dos dois estiver livre. Ocultos sob inserts em tela cheia. Mesmos requisitos dos inserts: script, qualificação para formato longo no servidor, 1080p e broll_policy=anyone explícito. O apresentador permanece na tela, então o preço não muda.
layout_windows	opcional	Reenquadramentos do apresentador ancorados em texto: split (somente 9:16) ou card. As janelas não podem se sobrepor umas às outras nem a um insert. Mesmos requisitos dos inserts. Um apresentador coberto ou desfocado ainda é trabalho entregue pelo fornecedor e é cobrado como tempo de rosto.
framing	opcional	Tamanhos do apresentador ancorados em texto: cada um muda para close ou plano médio nas palavras correspondentes e volta ao take em que elas terminam. Os itens não podem se sobrepor uns aos outros, a um insert ou a uma janela de layout. Um framing desenhado inteiramente sob templates em tela cheia é indicado em warnings[]. Quando uma ênfase punch_in coincide com um framing, o framing é aplicado. Exige script e qualificação para formato longo no servidor; o preço não muda.
templates	opcional	Modelos gráficos, cada um { id, kind, anchor, cover_words?, placement?, transition?, data }. Em qualquer execução de script. Os modelos nunca alteram o preço: cada execução é cobrada por suas partes conforme indicado em list_prices, e um apresentador coberto por um modelo ainda conta como tempo de apresentador. Os IDs são exclusivos entre inserts, overlays, layout_windows e templates. O texto deve estar em uma linha, usando letras latinas ou as letras do próprio script, dígitos e pontuação comum, sem emojis; um glifo CJK largo conta como 2 para o limite, e textos longos são reduzidos para caber na largura do tipo. size small|medium|large dimensiona um tipo; se ausente, é medium. Um campo de mídia recebe { asset_id } de um recurso pronto do tipo que ele nomeia. Uma citação interna nomeia palavras dentro das palavras do próprio modelo, depois da palavra anterior: sua batida ocorre na primeira palavra delas e não pode ficar sob um insert ou modelo de quadro inteiro; um clique ou etapa sem citação é distribuído uniformemente. Uma batida falada antes de o modelo entrar é movida para logo depois da entrada, com um aviso. Um modelo que alcança a faixa das legendas as oculta enquanto está visível; um modelo em outro lugar, como um pequeno no topo, deixa as legendas visíveis. Um modelo de quadro inteiro também oculta o apresentador, os overlays e os modelos sobre o apresentador enquanto está visível, nunca coincide com um insert de wipe ou zoom, e o apresentador coberto é cobrado. No máximo 3 overlays e modelos sobre o apresentador podem aparecer ao mesmo tempo, em áreas que não se sobrepõem. template_theme define a aparência de todos eles. Tipos: tag (over): uma pílula curta em gradiente sobre o apresentador ou um insert; sem position, fica no espaço das legendas e as oculta enquanto está visível; data text ≤ 32, position? top|center|bottom, size? small|medium|large. lower_third (over): uma barra de nome e função na parte inferior do quadro; as legendas ficam ocultas enquanto está visível; style ausente é clean_bar; data name ≤ 28, role? ≤ 36, side left|right, style? clean_bar|side_rule|soft_pill|mask_reveal, size? small|medium|large. end_card (over): uma pílula de site com uma chamada para ação opcional no espaço das legendas; as legendas ficam ocultas enquanto está visível; data site ≤ 32, cta? ≤ 48, size? small|medium|large. title_card (full): um cartão de abertura em quadro inteiro: o título (até duas linhas) em um cartão branco ao lado de uma imagem de logotipo opcional, e um chip opcional abaixo; data title ≤ 48, chip? ≤ 32, logo? {asset_id} image, size? small|medium|large. quote (full): um cartão de citação em quadro inteiro: aspas, o texto em até quatro linhas e, em seguida, o autor com uma foto redonda opcional, recortada em círculo; data text ≤ 120, author? ≤ 32, photo? {asset_id} image (recortada para preencher), size? small|medium|large. stat (full|over): um número que conta de 0 até value (até 2 casas decimais), com prefix e suffix ao redor e um rótulo abaixo; full preenche o quadro, over fica na altura do peito em um cartão; data value number, prefix? ≤ 6, suffix? ≤ 6, label? ≤ 32, size? small|medium|large. callout (over): uma seta ou um círculo que aponta para um ponto do quadro e pulsa, target {x,y} em % do quadro a partir do canto superior esquerdo, com uma pílula de rótulo opcional abaixo ou acima; pode apontar para o rosto, e o rótulo evita o rosto quando possível; também pode aparecer sobre um insert; data target {x,y}, style arrow|ring, text? ≤ 24, size? small|medium|large. checklist (over): 2–4 linhas, cada uma com um ícone opcional, um rótulo e um botão ou caixa de seleção definido como ligado ou desligado; um cursor clica nas linhas em sequência (item é o índice da linha, começando em 0), alternando seu estado a cada clique; abaixo do rosto; data items 2–4 de {label ≤ 24, on true|false, icon? phone|briefcase|user|clock|chat|star}, clicks? 0–6 de {item number, quote? citação interna}, style? switch|check, size? small|medium|large. phone_call (over): uma chamada recebida em um telefone neutro ao lado (à direita, a menos que side seja left): o chamador, uma legenda e um anel de avatar redondo; depois, a chamada é atendida em answer_at e o cronômetro começa (ou aparece uma faixa de espera); ao lado do rosto em quadros largos, abaixo dele em quadros altos; data caller ≤ 24, subtitle? ≤ 32, avatar? {asset_id} image (recortada para preencher), answer_at citação interna, side? left|right, size? small|medium|large, banner? ≤ 32, banner_note? ≤ 48, mask_number? true|false. compare (full): um cartão 3:5 em quadro inteiro mostrando a imagem anterior; em reveal_at, a imagem posterior entra em diagonal (reveal ausente) ou desliza da esquerda até um divisor central; ambas permanecem, com pílulas de rótulo opcionais; data before {asset_id} image (recortada para preencher), after {asset_id} image (recortada para preencher), labels? {before? ≤ 20, after? ≤ 20}, reveal_at citação interna, reveal? sweep|wipe, size? small|medium|large. notification (over): uma notificação de telefone no topo, acima do rosto: um ícone (ou a inicial do app), o app, um título e uma linha de texto; ela entra deslizando, permanece por pelo menos 1.2 s e sai antes do fim de sua duração; cada cartão da pilha entra deslizando por cima no seu at, empurrando os anteriores para trás; data app ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, stack? 1–2 de {app? ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, at? citação interna}, size? small|medium|large. progress (over): 2–5 etapas em uma coluna sobre um cartão, cada uma concluída com uma marca de seleção em sequência, na citação advance_at correspondente (uma por etapa, em ordem) ou distribuídas uniformemente; abaixo do rosto; data steps 2–5 de ≤ 20, advance_at? 2–5 de citação interna, size? small|medium|large. rating (over): cinco estrelas em um cartão, preenchidas em sequência até stars (1–5 em meios pontos, com meia estrela preenchida pela metade), com um rótulo opcional abaixo; na altura do peito; data stars number, label? ≤ 32, size? small|medium|large. chat_window (full): uma janela de chat em quadro inteiro: o prompt é digitado, a resposta aparece palavra por palavra, a tabela abre linha por linha e, em seguida, os cartões de resposta surgem, cada um no seu at ou distribuído uniformemente; zoom true aproxima e afasta nos momentos marcados; data app? ≤ 24, prompt ≤ 120, replies? 1–3 de {title ≤ 32, body? ≤ 64, at? citação interna}, answer? {text ≤ 150, at? citação interna}, table? {columns 2–3 de ≤ 16, rows 1–4 de {cells 2–3 de ≤ 20, at? citação interna}}, zoom? true|false, size? small|medium|large. video_grid (full): uma grade em quadro inteiro dos recursos de vídeo da conta, em blocos 9:16, 2x2 (células 1–4, com a coluna esquerda elevada) ou 3x1 (células 1–3); sem layout, as células fornecidas determinam a grade; cada bloco surge depois do anterior e é reproduzido sem som, com um título opcional acima; data layout? 2x2|3x1, cell_1 {asset_id} video (recortado para preencher), cell_2 {asset_id} video (recortado para preencher), cell_3 {asset_id} video (recortado para preencher), cell_4? {asset_id} video (recortado para preencher), title? ≤ 40, size? small|medium|large. word_title (full): um título cinético em quadro inteiro na cor de destaque: a primeira entrada aparece desde o primeiro quadro do modelo; cada entrada posterior aparece na sua citação at (geralmente as mesmas palavras faladas) ou é distribuída uniformemente; reveal replace (padrão) mostra uma entrada por vez, build acrescenta cada entrada ao título; data words 1–8 de {text ≤ 16, at? citação interna}, reveal? replace|build, size? small|medium|large. phone_screen (full): um telefone em quadro inteiro reproduzindo o vídeo da tela (sem som; um gradiente se não houver vídeo), cujos estados mudam em sequência, cada um na sua citação at ou distribuído uniformemente: lock (escurecido, com um cadeado e o texto), play (o vídeo nítido, com o texto no topo), liked (um coração e o texto), counter (uma pílula na parte inferior da tela), timer (um selo na borda superior), tag (um chip com uma linha indicadora na lateral da tela); lock, play e liked substituem uns aos outros, as tags se acumulam, e um counter ou timer posterior substitui o anterior; data screen? {asset_id} video (recortado para preencher), states 1–6 de {state lock|play|liked|counter|timer|tag, text? ≤ 24, at? citação interna}, size? small|medium|large. terminal (full): um cartão de terminal escuro em quadro inteiro: o comando é digitado; um diff abaixo dele recolhe suas linhas del (vermelhas) e abre suas linhas add (verdes) em diff.at; depois, uma linha de status com marca de seleção aparece em at; title nomeia o cartão; data title? ≤ 24, command ≤ 100, diff? {lines 2–7 de {text ≤ 36, change? add|del}, at? citação interna}, status ≤ 40, at? citação interna, size? small|medium|large. pointer_chips (over): 1–4 chips em uma coluna abaixo do rosto (à direita, a menos que side seja left), cada um ligado por uma linha curva a um ponto em seu target {x,y} em % do quadro a partir do canto superior esquerdo; aparecem em sequência na sua citação at ou distribuídos uniformemente; as linhas podem cruzar o rosto, mas os chips evitam cobri-lo; também podem aparecer sobre um insert; data items 1–4 de {target {x,y}, text ≤ 20, at? citação interna}, side? left|right, size? small|medium|large. chart (full): um gráfico de barras ou linhas em quadro inteiro, com 2–6 pontos rotulados em um cartão: em cada citação at de um ponto, ou distribuídos uniformemente, sua barra cresce ou a linha é desenhada até ele e seu valor aumenta até o valor final, com suffix depois dele; título acima; data type bar|line, title? ≤ 40, suffix? ≤ 6, points 2–6 de {label ≤ 12, value number, at? citação interna}, size? small|medium|large. race (full): uma corrida de barras classificadas em quadro inteiro: uma barra por nome, com a mais longa no topo; os valores da primeira rodada aparecem desde o início; depois, em cada citação at das rodadas seguintes, ou distribuídas uniformemente, as barras se movem para seus valores e trocam de posição conforme a classificação, com o rótulo da rodada abaixo; data title? ≤ 40, suffix? ≤ 6, names 3–6 de ≤ 14, rounds 2–5 de {label? ≤ 10, values 3–6 de number, at? citação interna}, size? small|medium|large. hand_title (full|over): um título escrito traço por traço em uma fonte manuscrita (até duas linhas), seguido de um marcador desenhado sobre as palavras do título a partir de mark.word (índice começando em 0) por mark.words (1 se ausente), em mark.at ou no fim do modelo; over fica no espaço das legendas e as oculta; data text ≤ 40, mark? {word number, words? number, style highlight|underline|circle, at? citação interna}, size? small|medium|large. word_fill (full): uma única palavra enorme em quadro inteiro cujas letras mostram seu vídeo (clip, reproduzido sem som), enquanto o restante do quadro usa o fundo do tema; ela cresce ao longo dos primeiros 10 quadros; data word ≤ 10, clip {asset_id} video, size? small|medium|large.
template_theme	opcional	A aparência de todos os modelos na execução: uma predefinição e um destaque opcional; somente com templates.
design	opcional	A identidade visual da execução: templates, o cartão final e o destaque das legendas são definidos por ela. Peça a marca ou use extract_brand; se ausente, usa o kit de marca salvo. Não pode ser usado com template_theme.
template_sounds	opcional	Aceito; o esquema ainda não tem uma descrição.
scenes	opcional	Elementos gráficos criados para este vídeo a partir das suas palavras, para o que nenhum modelo desenha: cada um é desenhado sobre o apresentador (over) ou no quadro inteiro (full) enquanto suas palavras são faladas; um elemento desenhado sobre as legendas as oculta enquanto está visível. O que não passar pela nossa verificação é omitido e indicado em warnings[]. 25 créditos por cena, com sua própria linha de citação, cobrados somente pelas cenas desenhadas no vídeo entregue. Requer script e qualificação para formato longo no servidor.
motion_style	opcional	Tipo aceito: object.
moves	opcional	Movimentos de list_moves aplicados às suas palavras: cada um { name, anchor: { quote }, cover_words?, placement?, data? }. Cada um é desenhado conforme descrito em sua linha de list_moves; data recebe os campos que ela nomeia. Um movimento que não possa ser desenhado sobre suas palavras ou neste vídeo é indicado em warnings[] e omitido, nunca descartado silenciosamente. Seus créditos constam na citação.
edit_sounds	opcional	Valores aceitos: true | false.
music	opcional	Música de fundo sob a voz, criada para este vídeo; desativada, a menos que você a solicite. "auto" escolhe o clima com base no script; { mood } o especifica com suas palavras, como "calm lo-fi". 60 créditos por vídeo, com sua própria linha na citação, cobrados somente quando o vídeo é entregue com música.
call	opcional	Uma chamada telefônica após uma citação: o apresentador escuta e depois congela enquanto a chamada é reproduzida como áudio telefônico, precedida por um toque; um telefone ao lado mostra a chamada (em vez disso, é usado um modelo phone_call que cubra a chamada). Requer script, quadro 9:16 e palavras depois da chamada. O apresentador congelado e a chamada acrescentam segundos de produção, não segundos de apresentador, e uma imagem de avatar ao vivo ainda exibida na chamada tem seu próprio preço em list_prices. Qualificação para formato longo no servidor.
interview	opcional	Uma entrevista: um locutor fora de cena diz as palavras marcadas do roteiro com a própria voz; o apresentador responde ao restante na tela e fica imóvel enquanto o locutor fala. Requer roteiro e qualificação para formato longo no servidor; os quadros em que o apresentador fica parado acrescentam segundos de produção, não segundos de apresentador.
presenter_gaze	opcional	Para onde o apresentador olha nessas palavras, do ponto de vista do espectador: câmera, esquerda ou direita. Requer actor_id com essa vista (list_actors); uma mudança de olhar é um corte.
shots	opcional	Planos ao vivo do ator em algumas palavras do roteiro: talking, talking_action (fala enquanto atua) ou action (atua enquanto as palavras são reproduzidas em narração). Os planos não podem se sobrepor; as palavras fora deles são gravadas na tomada habitual do apresentador. Requer quadro 9:16 e qualificação para formato longo no servidor; cada tipo tem seu próprio preço por segundo de apresentador em list_prices.
product_asset_id	opcional	A imagem do produto (ast_…) exibida nos planos com o produto.
person	opcional	AINDA NÃO É ACEITO: person ainda não é aceito: esta solicitação usa o ator padrão; escolha actor_id em list_actors ou forneça uma imagem para selecionar outro rosto
actor_id	opcional	ID de ator salvo do Clipwright, obtido em list_actors. Escolha actor_id, image ou person; não combine esses campos. Sem voice ou voice_id, a voz segue o gênero do ator. Não combine com actor_gender.
presenter_framing	opcional	close (padrão), wide (apresentador mais abaixo, com espaço acima) ou full (da cabeça aos pés). Requer a vista do ator com esse nome (list_actors), somente 9:16; full passa para wide e, depois, close, além de warnings[].
presenter_mic	opcional	true: o apresentador segura um microfone minúsculo. Requer a vista do ator com microfone nesse enquadramento (list_actors; as opções da biblioteca são wide); caso contrário, sem microfone e com warnings[].
image	opcional	URL https pública da foto do ator (PNG, JPEG ou WebP, até 10 MB). Um arquivo no disco deve primeiro passar por upload_image (POST /v1/uploads) — informe a url retornada. Uma fonte que não podemos usar — host privado ou de loopback, http, inacessível, com redirecionamento, acima de 10 MB ou que não seja um desses tipos de imagem — é recusada (unusable_source) antes de qualquer cobrança. Não detectamos o gênero do rosto: informe actor_gender ou voice; caso contrário, a voz masculina padrão será usada com um aviso.
actor_gender	opcional	Gênero do rosto em image: female | male. Somente com image: escolhe a voz padrão desse gênero (female: sarah, male: george; em gemini-3.8-flash-tts: kore e charon). Recusado com actor_id (o gênero é conhecido) e sem image. Uma voice ou voice_id explícita tem prioridade, e a resposta avisa que actor_gender não alterou nada.
name	opcional	AINDA NÃO É ACEITO: name ainda não é aceito: não chega ao renderizador
broll_policy	opcional	Política para B-roll: anyone permite pessoas, inclusive o ator; no_actor exclui o ator; no_people exclui todas as pessoas, inclusive mãos. Modelos com sua própria imagem ou vídeo precisam de "anyone"; caso contrário, são apenas armazenados. A substituição na execução tem prioridade sobre o padrão de ator da conta; caso contrário, usa-se no_people.
captions	opcional	Incorpora legendas sincronizadas com as palavras ao vídeo, sobre o apresentador e sobre as inserções. Não disponível com segments.
caption_style	opcional	Aparência das legendas quando captions=true. hormozi: padrão: letras maiúsculas brancas e pesadas com contorno preto espesso, até três palavras por trecho, uma palavra-chave por trecho em amarelo (a palavra enfatizada ou, caso contrário, a palavra mais longa que não seja uma palavra funcional). accent: letras maiúsculas brancas, condensadas e em negrito, sem contorno, até três palavras por trecho, uma palavra-chave por trecho em laranja (a palavra enfatizada ou, caso contrário, a palavra mais longa que não seja uma palavra funcional). tiktok: letras maiúsculas arredondadas em negrito, uma ou duas palavras por vez; a palavra falada fica amarela e aumenta de tamanho. youtube: fonte sem serifa, limpa e em negrito, quatro palavras (cinco em 16:9) em uma caixa escura arredondada perto da parte inferior; as palavras aparecem gradualmente, e a palavra falada fica vermelha. instagram: letras maiúsculas em estilo de quadrinhos com contorno rosa, duas palavras por vez; a palavra falada surge em laranja. minimalist: fonte sem serifa simples, quatro palavras em uma faixa escura semitransparente, com transição suave. neon: letras maiúsculas ciano com contorno magenta, duas palavras por vez; a palavra falada surge em branco. genz: letras maiúsculas grandes em estilo de quadrinhos, uma palavra por vez, surgindo com impacto e destaque rosa. campfire: letras arredondadas em estilo de quadrinhos, três palavras; as palavras faladas se iluminam em dourado e permanecem iluminadas. midnight: letras maiúsculas assustadoras, duas palavras, com transição lenta; a palavra falada fica vermelha. plottwist: fonte sem serifa pesada, três palavras; a palavra falada fica azul-celeste e aumenta de tamanho. headline: letras maiúsculas altas e condensadas em uma faixa preta sólida, três palavras; a palavra falada aumenta de tamanho em amarelo. promo: fonte sem serifa pesada em uma cápsula azul, três palavras; a palavra falada surge em amarelo. lecture: fonte sem serifa legível, quatro palavras em uma caixa escura arredondada; a palavra falada fica verde. highlighter: fonte sem serifa pesada, quatro palavras; as palavras faladas ficam verde-limão e permanecem iluminadas. studio: fonte sem serifa, quatro palavras digitadas em uma caixa escura desfocada; a palavra falada fica âmbar. broadcast: fonte sem serifa com contorno, quatro palavras na parte inferior do quadro; a palavra falada fica amarelo-claro. arcade: letras maiúsculas amarelas em blocos, duas palavras; a palavra falada surge em branco com um salto. clutch: letras maiúsculas em estilo de pincel, uma palavra por vez, surgindo com impacto em verde. bubblegum: letras arredondadas de exibição com contorno rosa, duas palavras; a palavra falada surge em amarelo com um salto. crayon: escrita à mão com marcador e contorno azul-marinho, duas palavras; a palavra falada surge em laranja. lyrics: escrita à mão cursiva, quatro palavras; as palavras faladas se iluminam em rosa e permanecem iluminadas. bassdrop: letras maiúsculas de exibição com contorno, uma palavra por vez, aumentando de tamanho em laranja. punch: preparação e impacto no meio do quadro: uma pequena linha introdutória branca acima de uma ou duas palavras-chave grandes, azuis e brilhantes; as demais palavras são pequenas e brancas. Alias: minimal desenha minimalist. Uma fonte que não consegue desenhar as letras do roteiro é substituída por uma fonte sem serifa simples. Pré-visualizações: https://clipwright.io/captions
caption_emphasis	opcional	Palavras-chave ou frases curtas a enfatizar, cada uma citada do script e correspondendo a uma citação de inserção (sem considerar maiúsculas, minúsculas e pontuação). Um item é a citação ou { quote, look }: look punch exibe uma pequena linha introdutória da mesma frase acima da citação como uma palavra-chave grande e brilhante; look pill exibe somente a citação em uma cápsula arredondada; look color exibe a citação na cor de destaque, no mesmo tamanho; look box exibe a citação em uma caixa suave na cor de destaque, no mesmo tamanho. Sem look, punch desenha punch; hormozi e accent desenham color; e os demais estilos exibem a citação em tamanho maior, na cor de destaque. Todas as ocorrências são enfatizadas. Requer captions=true e script; uma citação ausente do script é recusada antes de qualquer cobrança.
caption_mode	opcional	full (padrão quando omitido): todas as palavras faladas recebem legendas. highlights: as legendas aparecem somente ao redor das citações de caption_emphasis (introdução, citação, breve trecho final) e em nenhum outro lugar; requer caption_emphasis. Em ambos os modos, as legendas ficam ocultas enquanto uma inserção em tela cheia estiver na tela ou um modelo cruzar sua faixa.
caption_position	opcional	Onde as legendas aparecem: top, middle, lower ou bottom (80% da altura). Se omitido, usa a posição própria de caption_style. Requer captions=true.
caption_place	opcional	Em vez de caption_position, posiciona as legendas na altura definida por elas; as sobreposições nunca as movem, e uma sobreposição que cruze essa posição é recusada, a menos que seja colocada relative_to captions. Requer captions=true.
presenter_place	opcional	Altura e centro do rosto do apresentador no quadro. O retrato é enquadrado mais de perto para alcançar essa posição, usando a vista wide do ator quando a vista close estiver próxima demais; se até mesmo essa estiver próxima demais, warnings[] informa a altura do rosto exibido. Requer actor_id e script com overlays, inserts, layout_windows, framing ou call. O preço não muda.
look	opcional	AINDA NÃO É ACEITO: look ainda não é aceito: não chega ao renderizador
aspect_ratio	opcional	Formato de saída: 9:16 | 1:1 | 16:9. Se omitido, usa 9:16 sem image; com image, usa o formato compatível mais próximo do formato da imagem, inclusive se for paisagem — informe-o explicitamente sempre que passar image. Uma incompatibilidade acima de 15% entre a solicitação e a fonte é recusada (aspect_conflict) antes de qualquer cobrança.
resolution	opcional	Resolução de saída: 720p | 1080p (lado menor de 720 / 1080 px). Se omitido, usa 1080p.
voice	opcional	Nome da voz obtido em list_voices. Predefinições selecionadas: sarah | george | eric | daria_ru_female. A API recusa, antes de qualquer cobrança, um nome que list_voices não retorne. Se omitido, usa a voz padrão para o gênero do ator: o gênero de actor_id, actor_gender com image ou george para o ator padrão e para image sem actor_gender. gemini-3.8-flash-tts fala somente com as próprias vozes (kind model_voice em list_voices, como kore): indicar uma delas seleciona esse modelo, e uma voz é recusada antes de qualquer cobrança se o tts_model não puder reproduzi-la. Mutuamente exclusivo com voice_id.
voice_id	opcional	ID bruto de voz do fornecedor (16–32 letras e dígitos) para uma voz fora do catálogo. Verificado sob demanda: um ID desconhecido faz a execução falhar, não a solicitação. Recusado com tts_model=gemini-3.8-flash-tts. Mutuamente exclusivo com voice.
tts_model	opcional	Modelo de fala: eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5 | eleven_v4 | gemini-3.8-flash-tts. Se omitido, usa o modelo da voz escolhida (list_voices o mostra): gemini-3.8-flash-tts para as próprias vozes, eleven_v4 para todas as predefinições, vozes do catálogo e voice_id bruto. Um tts_model explícito tem prioridade, exceto eleven_v3: ele não é mais usado para fala, e uma execução que o indicar usa eleven_v4 com um aviso. eleven_v4 e gemini-3.8-flash-tts interpretam marcas de ênfase (uma vogal maiúscula dentro de uma palavra russa, "потОм", passa a ser uma; consulte script); eleven_flash_v2_5 e eleven_turbo_v2_5 são alternativas mais baratas para idiomas que não sejam russo. gemini-3.8-flash-tts fala somente com as próprias vozes (list_voices com model=gemini-3.8-flash-tts; sem voice, kore para uma atriz e charon nos demais casos) e não retorna tempos por palavra: uma voz predefinida ou do catálogo, voice_id, captions=true, segments e inserts são recusados com esse modelo antes de qualquer cobrança. As tags de áudio entre colchetes são uma convenção dos outros modelos de fala e não são medidas por ele. Limites de script por modelo de fala: eleven_v3: 5000 caracteres; eleven_flash_v2_5: 10000 caracteres; eleven_turbo_v2_5: 10000 caracteres; eleven_v4: 5000 caracteres; gemini-3.8-flash-tts: 5000 caracteres. A contagem inclui espaços, tags de áudio e marcas de ênfase; emojis podem contar como dois caracteres. As tags de pausa são removidas do texto enviado a eleven_v4 e gemini-3.8-flash-tts e não são contabilizadas nesses modelos. Não há limite de palavras. A duração e o preço são estimativas até serem medidos.
voice_pace	opcional	Velocidade da narração; 1 é a velocidade natural da voz. gemini-3.8-flash-tts recebe uma indicação de estilo; eleven_v4 não tem controle de velocidade, então escolha uma voz com base em words_per_second de list_voices; ambos são indicados em warnings[].
pause_trim	opcional	Corta pausas acima destes s; false mantém todas. Padrão com templates, scenes, shots: 0.15 para frases, 0.08 para vírgulas.
end_hold_s	opcional	Segundos durante os quais o último quadro permanece após a última palavra: o apresentador congela, e todas as camadas na tela permanecem. Segundos de produção, não segundos de apresentador. Requer script e qualificação para formato longo.
visible_ai_label	opcional	Rótulo de IA visível para novos vídeos de apresentador marcados, inclusive em formato longo; o padrão é true na política de admissão do servidor. False oculta somente o rótulo visível e não desativa a marcação invisível nem a procedência assinada. As saídas históricas não são alteradas.
background	opcional	Valores aceitos: white | blur | contain.
create_actor. Crie um ator pessoal para esta conta a partir de palavras que descrevam um adulto fictício: um retrato 9:16 com exatamente um rosto, além dos outros formatos solicitados editados a partir dele. Retorna um run_id imediatamente; consulte get_run até 'succeeded' (created_actor.actor_id; depois, passe-o como actor_id para make_ugc) ou 'failed'. Cada imagem publicada é cobrada pelo preço exibido na cotação; descrições recusadas e retratos inutilizáveis não custam nada. Quando a geração estiver desativada, a chamada falha com actor_generation_disabled. from_actor_id mantém o rosto (verificado; uma incompatibilidade não custa nada). Com style_reference, um retrato que se pareça com uma pessoa na foto é recusado sem cobrança, e o preço é o mesmo. portrait (com gender e approximate_age) torna-se o retrato 9:16 sem cobrança; somente os outros formatos são cobrados. Uma imagem sem exatamente um rosto, ou com o rosto cortado, pequeno ou grande demais, é recusada sem cobrança. Um mascote de marca desenhado com generate_image pode ser esse retrato quando seu rosto parecer um rosto humano (uma pessoa de desenho animado); um mascote animal ou objeto é recusado, então mostre-o em inserções.

Campo	Obrigatório	O que significa
description	opcional	Palavras que descrevem um adulto fictício: aparência, roupas, cenário. Mencionar uma pessoa real ou uma semelhança com ela é recusado antes de qualquer cobrança (actor_prompt_refused). Obrigatório, a menos que from_actor_id ou portrait seja informado; com from_actor_id, define a aparência, as roupas e a pose da imagem, enquanto gênero e idade permanecem os da origem.
gender	opcional	female | male. Define o gênero do ator e a voz padrão dos vídeos com esse ator. Obrigatório, a menos que from_actor_id seja informado.
approximate_age	opcional	Idade aproximada em anos, de 18 a 90: os atores são adultos. Obrigatório, a menos que from_actor_id seja informado.
name	obrigatório	Nome exibido em list_actors.
aspect_ratios	opcional	Formatos a criar: 9:16 | 1:1 | 16:9, sempre incluindo 9:16. Se omitido, os três formatos são criados. Formatos que não passarem na verificação de identidade não são cobrados e são indicados em warnings.
from_actor_id	opcional	Derive um novo ator pessoal a partir deste (um ator da biblioteca ou seu próprio): o mesmo rosto, gênero e idade, com a imagem alterada por enquadramento, objetos nas mãos, cenário, description ou style_reference. Omita gender e approximate_age.
framing	opcional	Tamanho do plano: close (padrão, do peito para cima), wide (da cintura para cima, com as mãos e espaço acima) ou full (em pé, da cabeça aos pés). A partir de palavras, define o enquadramento do novo retrato; com from_actor_id, wide ou full afasta a câmera. A imagem é classificada pelo tamanho do rosto desenhado, e make_ugc a renderiza com presenter_framing desse nome. Não pode ser usado com style_reference ou portrait, cuja imagem define o plano.
holding	opcional	Até 2 objetos que o apresentador segura, um em cada mão.
setting	opcional	O cômodo ou plano de fundo em que o apresentador deve aparecer, descrito em palavras.
style_reference	opcional	Uma foto PNG ou JPEG cujo cenário, iluminação, ângulo da câmera, tamanho do plano e roupas serão seguidos pelo novo retrato: do peito para cima, da cintura para cima ou corpo inteiro, conforme a foto; um retrato mais aberto que o plano do peito para cima se torna uma imagem wide. Um recurso de imagem desta conta (upload, importação por URL ou imagem encontrada, rights_confirmed). Sem from_actor_id, o rosto é novo, criado a partir de description; com ele, é o rosto do ator de origem. Um retrato que se pareça com uma pessoa na foto é recusado sem cobrança.
portrait	opcional	Crie o ator a partir da sua própria imagem de retrato, em vez de gerar uma: um recurso de imagem PNG ou JPEG desta conta (rights_confirmed), com proporção dentro de 2% de 9:16 e mostrando exatamente um rosto que não esteja cortado nem pequeno ou grande demais. Ela se torna o retrato 9:16 do ator sem cobrança; os outros formatos são editados a partir dela e cobrados normalmente. Deve ser usado com gender e approximate_age; não pode ser usado com description, style_reference ou from_actor_id.
quality	opcional	Qualidade da imagem: medium | high. Se omitido, será medium. high produz o retrato mais natural. O preço por imagem depende dessa opção; a cotação o mostra antes de qualquer cobrança.

make_faceless. Inicie um vídeo faceless finalizado e pago a partir de um roteiro ou briefing. Você seleciona de 30 a 90 segundos; o vídeo termina com a narração, dura pelo menos 25 segundos (um vídeo explicativo dura o mesmo que a narração) e, no máximo, até um quarto além da duração selecionada, sem nunca ultrapassar 90 segundos. O vídeo tem um clipe animado de abertura e cenas com imagens. As legendas ficam ativadas por padrão e podem ser desativadas.

Retorna um run_id imediatamente; consulte get_run com seus poll.arguments até 'succeeded' (video_url) ou 'failed'. attempt=2,3,… inicia uma NOVA execução para a mesma entrada.

Campo	Obrigatório	O que significa
input_mode	obrigatório	'script' narra seu texto exato; 'brief' escreve a narração a partir de uma descrição curta. Envie exatamente um entre script e brief, de acordo com este modo.
script	opcional	A narração, lida como escrita. Obrigatório quando input_mode for 'script'; deve estar ausente quando for 'brief'.
brief	opcional	O tema do vídeo; a narração é escrita a partir dele. Obrigatório quando input_mode for 'brief'; deve estar ausente quando for 'script'.
duration_seconds	obrigatório	Duração selecionada, de 30 a 90 segundos, em um limite de quadro de 1/25 s. O vídeo termina com a narração e dura pelo menos 25 segundos (um vídeo explicativo dura o mesmo que a narração), geralmente no máximo até um quarto além da duração selecionada e 90 segundos; quando a narração demora mais, o vídeo vai até o fim dela. Um vídeo que ultrapasse a duração selecionada em mais de 5 segundos informa isso em warnings[]. A cobrança nunca excede a cotação. Um roteiro é aceito quando sua duração estimada fica entre 21 segundos e a duração selecionada mais 5, até o máximo de 90.
style_reference	opcional	Imagem pública https cujo estilo visual será seguido pelas cenas.
character_reference	opcional	Imagem pública https de uma pessoa ou figura que deve permanecer consistente entre as cenas.
character_details	opcional	Detalhes visuais fixos dessa pessoa ou figura, como cabelo, roupas e acessórios ausentes; mantidos em todas as cenas geradas.
scene_images	opcional	Suas imagens, cada uma posicionada em um intervalo de palavras ou citação da narração.
captions	opcional	Legendas incorporadas ao vídeo; ativadas por padrão.
transitions	opcional	Flash ou vazamento de luz nos cortes, com seu som: em cada mudança de cena ou na mudança mais próxima de cada âncora (somente para script). Se omitido em um brief: flash em cada mudança de cena; false para cortes simples. Sem custo adicional.
edit_sounds	opcional	Um som baixo em cada mudança de cena, com o pico no corte; template_sounds.edit seleciona o som. Preço inalterado.
template_sounds	opcional	false para nenhum som, ou { flash, whoosh (vazamento de luz), edit: name } de list_template_sounds.
music	opcional	Música de fundo sob a voz, criada para este vídeo; desativada, a menos que você a solicite. "auto" escolhe o clima com base no roteiro; { mood } descreve o clima com suas palavras, como "calm lo-fi". 60 créditos por vídeo, em uma linha própria na cotação, cobrados somente quando o vídeo é entregue com música.
templates	opcional	Somente para script: como em make_ugc, um espaço pode exibir seu recurso de imagem ou vídeo (asset_id, rights_confirmed). Grátis.
shots	opcional	Somente para script: 1-10 {id, anchor, action, asset_id?}, no máximo 5 s cada.
scenes	opcional	Somente para script: como as cenas de make_ugc.
motion_style	opcional	Como motion_style de make_ugc; somente para script. Grátis.
moves	opcional	Somente para script: movimentos de list_moves baseados nas suas palavras: cada um { name, anchor: { quote }, cover_words?, placement?, data? }. Cada movimento é desenhado conforme descrito em sua linha em list_moves; data recebe os campos que ela especifica. Um movimento que não possa ser desenhado com as palavras indicadas ou neste vídeo é mencionado em warnings[] e omitido, nunca descartado sem aviso. Os créditos correspondentes aparecem na cotação.
format	opcional	'explainer': um vídeo explicativo desenhado em estilo de cartoon, com um evento em cada palavra e um personagem principal no canto; somente para script. É adequado a uma sequência de ações concretas narradas por uma pessoa: um tutorial passo a passo, como algo funciona, um fluxo de trabalho, uma demonstração de ferramenta, N erros ou N maneiras, com algo para mostrar em cada frase. Raciocínios sem ações, diálogos ou histórias sobre pessoas não se encaixam bem. Cada cotação de roteiro informa explainer_fit: ofereça o formato quando for adequado; quando não for, explique o motivo e mostre como reescrever em ações antes de perguntar. O personagem principal é desenhado a partir de character_reference ou character_details (sua pose aparece na cotação); caso contrário, usamos o nosso, sem custo. Uma lista de itens nomeados recebe uma imagem de cada item em sua cena, uma para cada item na cotação, cobrada somente quando exibida. Sem voz, um roteiro em inglês é lido pela nossa voz mais rápida.
pause_trim	opcional	Somente para script: como pause_trim de make_ugc, com o mesmo padrão para templates, scenes, shots ou format explainer.
voice	opcional	Voz da narração: um nome de list_voices com skill=make_faceless (kind faceless_voice). Se omitido, será narrator_en_wise_lady; para um vídeo explicativo em inglês, será a voz mais rápida. Escolha uma voz no idioma da narração: uma voz lê qualquer idioma com seu próprio sotaque. A API recusa um nome desconhecido e uma voz de make_ugc antes de qualquer cobrança. Um voice_id bruto não é aceito aqui.

• Um vídeo faceless não tem apresentador diante da câmera: a narração é reproduzida sobre um clipe animado de abertura e cenas com imagens. Envie exatamente um entre script e brief, conforme indicado por input_mode.
• duration_seconds é uma meta, não uma duração à qual o vídeo será esticado: o vídeo termina com a narração, que dura pelo menos 25 segundos (um vídeo explicativo dura apenas o tempo da narração) e geralmente, no máximo, até um quarto além de duration_seconds e 90 segundos; uma narração mais longa vai até o fim. Um vídeo que ultrapasse a duração em mais de 5 segundos informa isso em warnings[]. A cobrança nunca excede a cotação.
• As legendas removem a pontuação, mantêm acentos e outros sinais diacríticos e exibem os números como foram escritos. Com as legendas ativadas, o roteiro é verificado em relação à fonte das legendas antes da criação da fala; se a fonte não puder desenhar um caractere, a execução falha sem cobrança.
• O idioma da narração é detectado automaticamente.
• voice define a voz da narração: escolha um nome em GET /v1/voices?skill=make_faceless. Sem essa opção, a narração é lida por narrator_en_wise_lady e um vídeo explicativo em inglês usa a voz mais rápida. Escolha uma voz no idioma da narração. Um nome desconhecido, uma voz de make_ugc e voice_id são recusados antes de qualquer cobrança: make_faceless usa somente as vozes listadas para ele.
• make_faceless sempre entrega vídeos em 1080p e 9:16. Quando a geração faceless estiver desativada no servidor, ambas as chamadas retornam paid_render_disabled e nada é cobrado.
• Uma execução com falha cujo erro começa com story_not_planned foi interrompida na primeira etapa: não foi possível planejar a narração nessa tentativa. Nada foi cobrado, e a mesma entrada pode ser executada novamente com uma nova Idempotency-Key.

Para make_ugc e create_actor, o formato de saída segue a solicitação e a origem. Os formatos compatíveis são 9:16, 1:1, 16:9 e as resoluções 720p, 1080p; sem especificação, será 1080p em 9:16.

08

Fluxos de trabalho

GET /v1/public/workflows lista os métodos que podem ser executados. Os métodos nativos são ugc-product-intro, ugc-faq-answer, faceless-explainer e product-image-story. website-proof-demo e kinetic-launch ainda não podem ser executados e permanecem execution_blocked, com os motivos correspondentes.

O caminho mais curto com a CLI começa pelo exemplo do próprio método. Somente plan-run consome créditos; todos os comandos anteriores são gratuitos. Edite o briefing antes de criar o plano e mantenha os pins do método.

clipwright workflow-show faceless-explainer > method.json
jq '{document: {v: 1, method: {method_id: .descriptor.id, version: .descriptor.version, content_digest: .descriptor.content_digest, capability_digest: .capabilities.content_digest}, brief: .descriptor.example.brief, beats: .descriptor.example.beats, claims: [], assets: []}}' method.json > create.json
clipwright plan-create --file create.json > plan.json
jq '{revision, content_digest}' plan.json > approval.json
clipwright plan-approve wfp_example --file approval.json
clipwright plan-quote wfp_example > quote.json
jq '{revision, content_digest, semantic_input_digest, quote_id, idempotency_key: "workflow-example:1"}' quote.json > launch.json
clipwright plan-run wfp_example --file launch.json
clipwright runs run_example

Substitua wfp_example pelo plan_id de plan.json e run_example pelo ID de execução exibido por plan-run. Uma cotação expira cinco minutos após ser emitida, então execute plan-run logo após plan-quote. Para product-image-story, envie cada foto com clipwright upload --json. A resposta fornece upload_id e content_digest; copie-os diretamente para o asset. Adicione um asset por foto. O comando uploads retorna a mesma identidade para um upload anterior.

clipwright upload mug-front.jpg --json > upload.json
jq '{instance_id: "mug-front", asset_id: .upload_id, content_digest, anchor: {quote: "overall shape"}, provenance: "owner_supplied", rights: "owner_authorized", purpose: "product_proof"}' upload.json > asset.json

{
  "instance_id": "mug-front",
  "asset_id": "upl_00000000000000000000000000000000",
  "content_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "anchor": {
    "quote": "overall shape"
  },
  "provenance": "owner_supplied",
  "rights": "owner_authorized",
  "purpose": "product_proof"
}

• Crie um plano pertencente à conta, salve revisões e aprove a revisão e o content_digest exatos. O planejamento e a aprovação não custam nada e não iniciam nenhuma renderização. Uma revisão editada precisa de uma nova aprovação.
• Para um plano aprovado, envie um corpo vazio para /v1/workflow-plans/{id}/quote usando POST. Use quote_id, revision, content_digest e semantic_input_digest na solicitação de execução. Verifique expires_at antes de iniciar uma nova compra; esse campo é metadado da cotação. Idempotency-Key deve ser igual ao idempotency_key do corpo.
• As cotações de workflow UGC informam em native_quote.quote.warnings que duration_estimate_sec e credits_estimate são estimativas, não um preço fixo. O UGC curto entregue é cobrado de acordo com seus price_lines, com base no vídeo medido e arredondado para cima em segundos inteiros; portanto, um vídeo mais longo que o estimado custa mais que a estimativa. Leia credits_charged na execução concluída. Uma cotação nativa com long_form_pricing usa, em vez disso, os intervalos de rosto entregues e verificados e a tarifa congelada na admissão, não a duração total do vídeo. Os termos nativos para falhas continuam valendo.
• A tarifa nativa e as regras para falhas continuam valendo. faceless duration_seconds seleciona a duração cuja cotação limita a cobrança; a narração medida determina a duração entregue. Voz, legendas e o roteiro exato aceito mantêm suas configurações nativas.
• Vincule cada imagem fornecida a um instance_id distinto, asset_id de upload estável e pertencente à conta, content_digest, direitos, proveniência, finalidade e um intervalo de palavras sem sobreposição ou uma citação inequívoca. Reutilize um upload em várias instâncias; URLs assinadas temporárias são resolvidas na cotação e no lançamento.
• A comprovação original do produto ocupa tomadas IMAGE compatíveis. A abertura gerada é ilustrativa. Uma apresentação de slides exata composta apenas por imagens estáticas, uma abertura somente com clientes e layouts de cena arbitrários não estão disponíveis quando forem obrigatórios.
• Um protected_area é um retângulo em frações da imagem de origem. A pré-verificação deve preservá-lo durante o recorte, o movimento PAN e as legendas. Orientação ou posicionamento da imagem sem comprovação são recusados; uma imagem gerada nunca substitui a comprovação original exigida.
• PNGs protegidos com animação ou blocos EXIF e JPEGs com qualquer segmento APP1 (EXIF/XMP) são recusados. Exporte uma cópia estática na orientação correta, sem esses metadados. A cobertura usa o relógio de quadros nativo medido de 25 fps.
• A retenção do upload e a URL assinada de 24 horas são limites independentes; uma cotação não estende nenhum deles. As fontes e assinaturas devem permanecer disponíveis para renderização e recuperação. Uma repetição aceita mantém suas fontes e assinaturas originais.
• Um lançamento bem-sucedido retorna o recibo e sua Run nativa existente. Repita a mesma solicitação aceita para recuperar essa compra, inclusive após a expiração da cotação ou quando a assinatura da fonte deixar de estar disponível. Leia o progresso e o vídeo entregue por meio de GET /v1/runs/{id}.
• Planos privados pertencem à conta do token.
• Para product-image-story, as cenas geradas e a imagem de abertura usam os dois primeiros originais distintos e elegíveis de product_proof na ordem dos assets aceitos. O primeiro ancora o formato do produto; o segundo fornece outra perspectiva. A prontidão do plano e a cotação nativa informam a quantidade selecionada e que as ilustrações geradas podem ser diferentes. Os originais adicionais mantêm seus posicionamentos de imagem vinculados exatos. A recuperação de um checkpoint pago mais antigo reutiliza as cenas existentes com um aviso explícito quando não é possível verificar o condicionamento pelo produto original. Revisões e candidatos, incluindo candidatos mantidos e revisões posteriores, preservam essa limitação conhecida de condicionamento, sem prometer que as cenas ou os posicionamentos antigos sobreviverão à edição.
• As gravações rejeitam campos desconhecidos e documentos com mais de 256000 bytes JSON. As leituras aceitam campos e valores de enumeração futuros; campos desconhecidos dentro de um documento lido são preservados, para que um cliente mais antigo recuse uma gravação não compatível em vez de apagar a intenção. Mantenha a narração bruta aceita inalterada.
• Após perder a resposta de uma gravação, repita a mesma solicitação explícita de base_version/document. Se ela já tiver se tornado o documento atual, o backend retorna essa revisão sem redefinir a aprovação; um documento atual diferente gera workflow_conflict. SDK, MCP e CLI nunca aprovam, cotam ou compram como efeito colateral de uma gravação.
• GET /v1/runs/{id} pode incluir workflow: seu recibo imutável, approved_plan, estado/avisos nativos, actual_output, asset_placements, beat_dispositions consultivos, validation_issues e creative_acceptance=not_reviewed. approved_plan omite brief.reference_profile, portanto uma consulta de status não o repete; o que o plano não reproduz da referência aparece nos avisos, e GET /v1/workflow-plans/{id} retorna a revisão atual completa. A execução mantém a revisão comprada mesmo após a alteração do rascunho. Uma revisão ou um candidato de tomada nunca herda o recibo de seu antecessor.
• A liquidação faceless verificada fornece o digest do artefato, o formato e a duração medida, mesmo que falte geometria opcional posteriormente. Os posicionamentos exigem um checkpoint íntegro vinculado à conta/execução/solicitação; a comprovação ausente é null, com um problema de validação. Uma lista de posicionamentos vazia e verificada é []. A entrega UGC verificada fornece o formato, a duração e o digest medidos do arquivo final; o formato vem das dimensões medidas, não da solicitação. UGC sem comprovação de bytes/formato, incluindo execuções mais antigas, tem actual_output=null com output_evidence_unavailable; seu video_url nativo continua sendo o resultado. Evidências históricas não renovam uma URL de download expirada nem comprovam a aceitação criativa humana.
• Os métodos do SDK são listWorkflows, getWorkflow, createWorkflowPlan, planReferenceRemake, getWorkflowPlan, saveWorkflowPlan, approveWorkflowPlan, quoteWorkflowPlan e runWorkflowPlan; getRun preserva as evidências do workflow. Os comandos da CLI são workflows, workflow-show, plan-create --file, plan-show, plan-save --file, plan-approve --file, plan-quote e plan-run --file. Esses comandos de workflow exibem JSON; os arquivos são limitados a 1 MiB antes da análise. Um arquivo plan-show pode ser editado e passado para plan-save para o mesmo plano.

Exemplo de corpo para POST /v1/workflow-plans/{id}/run: substitua os campos da cotação pela cotação do seu plano aprovado e envie Idempotency-Key: workflow-example:1.

{
  "quote_id": "wq_example",
  "revision": 1,
  "content_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "semantic_input_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "idempotency_key": "workflow-example:1"
}

09

Iniciar uma execução

Uma chamada paga leva um cabeçalho além da chave: Idempotency-Key. POST /v1/skills/make_faceless/run, POST /v1/runs/{id}/revisions, POST /v1/runs/{id}/candidates, POST /v1/skills/make_ugc/run, POST /v1/skills/create_actor/run, POST /v1/workflow-plans/{id}/run, POST /v1/skills/generate_image/run, POST /v1/skills/generate_video/run, POST /v1/reference-analyses, POST /v1/creator-profiles e POST /v1/trend-searches exigem esse cabeçalho, e uma chamada sem ele é recusada com 400 idempotency_key_required antes de qualquer cobrança.

• Você escolhe a chave, e ela é o único elemento que diferencia uma repetição de um segundo pedido. Qualquer string exclusiva serve; mantenha-a enquanto houver possibilidade de reenviar a chamada.
• A mesma chave com o mesmo corpo retorna a execução que já iniciou e não cobra novamente. É isso que torna segura uma repetição comum.
• A mesma chave com um corpo diferente é recusada com 409 idempotency_key_reused. Use uma nova chave para uma nova solicitação, em vez de editar uma solicitação sob uma chave já utilizada.
• Para iniciar uma execução deliberadamente nova com a mesma entrada — uma repetição após uma falha — envie uma nova chave. A execução pela qual você já pagou permanece como está.
• @clipwright/sdk e @clipwright/mcp-server criam a chave para você com base no cliente e na entrada, e transformam attempt=2, 3 … em uma nova chave. Em HTTP simples, você escolhe a chave.

10

Quando uma chamada falha

Toda recusa inclui um objeto de erro com um código e uma mensagem. O que fazer depende do tipo de recusa, não do texto:

Recusa	HTTP	Repetir a mesma chamada?	O que fazer	Cobrança
rate_limited	429	sim, após a espera	Controle de fluxo, não um erro: a resposta informa quantos segundos esperar, em Retry-After e no corpo.	Nada. A chamada não foi aceita.
server_error	500, 502, 503	sim, após a espera	A falha está no servidor. Não inicie uma segunda execução com uma nova chave de idempotência: a mesma chamada é a repetição.	Não por esta resposta. Uma execução que o servidor não conseguiu iniciar tem seus créditos reservados devolvidos; uma execução que foi iniciada é cobrada uma vez, de acordo com seu próprio resultado.
insufficient_credits	402	não, a resposta será a mesma	Pare e informe à pessoa o saldo e o preço; ambos estão no corpo. Repetir não altera nenhum dos dois.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
debt_outstanding	402	não, a resposta será a mesma	Pare. A compra de créditos quita a dívida antes que qualquer valor chegue ao saldo, removendo o bloqueio.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
not_admitted	403	não, a resposta será a mesma	Pare. A conta não tem acesso beta; nem uma repetição nem uma compra alteram isso. Entre em contato com o suporte.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
edit_conflict	409	não, a resposta será a mesma	Pare. O rascunho da edição está em uma versão diferente daquela em que a gravação se baseou; o corpo informa qual. Leia o rascunho: se ele já contiver seu documento, uma gravação anterior foi concluída. Caso contrário, aplique a alteração ao que leu e grave usando a versão correspondente.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
run_not_editable	409	não, a resposta será a mesma	Pare. A execução não tem um rascunho de edição para ler ou gravar. O corpo informa o estado e o motivo, os mesmos que aparecem nas tomadas da execução.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
editing_closed	503	não, a resposta será a mesma	Pare. Edições pagas não estão disponíveis; o corpo informa o motivo. Nada foi cobrado e nenhuma execução foi criada, e paid_edits nas tomadas da execução informa quando elas estarão disponíveis.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
edit_ceiling_reached	409	não, a resposta será a mesma	Pare. O original atingiu o limite de revisões ou de candidatos de tomada (cada um contado separadamente) em execução, ou com falha e ainda não concluídos; o corpo informa o limite, a contagem e as execuções. Acompanhe uma execução em andamento com GET /v1/runs/{id} e inicie a próxima após sua conclusão; o suporte aumenta o limite de falhas de revisões após uma falha nossa.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
edit_invalid	422	não, a resposta será a mesma	Pare. O documento ou a operação solicitada por um candidato de tomada viola as regras da execução que está sendo editada; issues lista cada problema na ordem. Corrija a solicitação: as regras estão nas tomadas da execução.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
workflow_invalid	400	não, a resposta será a mesma	Pare. Leia todos os problemas e avisos e, em seguida, corrija o documento do workflow. Aprovação, cotação e lançamento pago são chamadas explícitas separadas.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
workflow_conflict	409	não, a resposta será a mesma	Pare. Leia o plano salvo e compare sua revisão e seu documento com a solicitação original. Recupere um lançamento incerto com a solicitação e a chave de idempotência originais; uma nova chave pode resultar em cobrança duplicada.	Nada por esta chamada. Um lançamento concluído anteriormente é cobrado uma vez, de acordo com seu próprio resultado; a solicitação e a chave originais o retornam.
workflow_not_ready	409	não, a resposta será a mesma	Pare. Leia todos os problemas e avisos. Resolva os requisitos de prontidão e, em seguida, aprove e cote explicitamente a revisão escolhida antes de um lançamento pago com chave.	Nada. A chamada foi recusada antes de criar uma execução ou reservar créditos.
client_error	400, 401, 403, 404, 409, 410, 413, 415, 422, 503	não, a resposta será a mesma	Pare. A própria solicitação foi recusada: leia a mensagem, corrija a chamada e envie-a novamente.	Nada por esta chamada: ela não criou nenhuma execução nem reservou créditos. Uma execução iniciada anteriormente com o mesmo Idempotency-Key (409 idempotency_key_reused) é cobrada uma vez, de acordo com seu próprio resultado.
Estes são todos os códigos que a API coloca em error.code. Um código que você ainda não viu segue a linha correspondente acima, porque a linha é escolhida pelo status:

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• analysis_enqueue_failed
• aspect_conflict
• asset_cap_exceeded
• asset_ingest_cap_exceeded
• asset_not_found
• asset_not_ready
• assets_disabled
• creator_profile_limited
• creator_profile_not_found
• creator_url_unsupported
• debt_outstanding
• deletion_held
• edit_ceiling_reached
• edit_conflict
• edit_invalid
• editing_disabled
• editing_not_priced
• editing_window_not_set
• feedback_limited
• generations_disabled
• generations_marking_pending
• idempotency_key_required
• idempotency_key_reused
• ingest_enqueue_failed
• insufficient_credits
• insufficient_scope
• internal_error
• invalid_image
• invalid_request
• malformed_body
• no_changes
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• reference_analysis_disabled
• reference_analysis_limited
• reference_analysis_not_found
• reference_not_analyzable
• reference_not_usable
• reference_url_unsupported
• rejected_field
• revision_needs_generated_unit
• rights_not_confirmed
• run_media_in_use
• run_not_editable
• run_not_finished
• run_not_found
• script_encoding_lost
• source_aspect_mismatch
• source_not_usable
• trend_search_limited
• trend_search_not_found
• trends_unavailable
• unauthorized
• unknown_field
• unsupported_combination
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upload_digest_mismatch
• upload_expired
• upload_in_use
• upload_not_finished
• upload_size_mismatch
• upstream_error
• url_fetch_busy
• url_fetch_failed
• url_fetch_rate_limited
• url_fetch_refused
• url_import_disabled
• workflow_conflict
• workflow_invalid
• workflow_not_ready

11

Limites

• 60 solicitações pagas e 300 gratuitas a cada 60 segundos. A janela é contabilizada por conta, não por chave, então chaves extras não aumentam a capacidade.
• São produzidos ao mesmo tempo, por conta, 3 vídeos com apresentador e 2 vídeos sem rosto; os demais entram na fila e não são recusados. Quando muitas contas renderizam ao mesmo tempo, uma execução também pode esperar sua vez atrás delas.
• Uma recusa por limite de taxa informa os segundos de espera em Retry-After e no corpo da resposta. Respeite o maior dos dois valores.
• 99 inserções por clipe e, no máximo, 16 aparições do ator entre elas. Ambos são contabilizados com base nos índices de palavras enviados, então uma solicitação que exceda esses limites é recusada antes de qualquer cobrança.
• cover_words informa quantas palavras faladas uma inserção cobre, contando a partir da primeira palavra da âncora. A inserção termina onde começa a primeira palavra não coberta; assim, duas inserções com coberturas que se encontram ficam adjacentes e não deixam nenhuma cena do ator entre elas.
• A proporção de palavras que você deixa sem cobertura determina a proporção do clipe que mostra um rosto, e não varia com a velocidade da voz. O comprimento das palavras varia: em um roteiro de 560 palavras, pedir 19% resulta em cerca de 16 a 22; em um roteiro mais curto, a variação é maior, e uma voz diferente também altera o resultado.
• Duas escolhas de uma única palavra alteram o preço, não apenas a aparência. Uma inserção ancorada na palavra 0 inclui o silêncio antes da primeira palavra; ancorada na palavra 1, deixa uma aparição extra do ator, e cada aparição aumenta o preço. A cobertura que chega à última palavra leva o clipe até o fim e remove a aparição final da mesma forma.
• Uma cotação informa a proporção como estimatedFaceWordShare. Leia esse campo; não divida estimatedFaceSeconds por estimatedTotalDurationSec. Esses dois valores respondem a perguntas diferentes — o primeiro é a reserva que mantemos no limite mais lento da faixa de fala, o segundo é a duração esperada do clipe — e a proporção entre eles não representa a participação de nada.

12

O que esta API nunca fará

• Publicar qualquer coisa. Retornamos um arquivo e um link assinado; cabe a você decidir onde ele será publicado.
• Cancelar uma execução iniciada. Não há endpoint para isso.
• Aceitar estes campos de make_ugc: character, broll_url, disclosure_overlay, webhook_url. Eles são recusados pelo nome antes de qualquer cobrança, não são aceitos nem silenciosamente ignorados.
• Alterar o formato ou a resolução solicitados sem avisar. Uma incompatibilidade é ajustada com um aviso ou recusada antes da chamada paga.
• Entrar em contato com você. Não há webhooks: consulte a execução com GET /v1/runs/{id}.
• Exibir uma chave uma segunda vez ou recuperá-la de um backup.

13

Também vale saber

• Avisos, não silêncio. Tudo o que não pudermos atender será informado em warnings[] na mesma execução, com o nome correspondente. Nenhum parâmetro desaparece sem uma observação.
• Um servidor MCP. @clipwright/mcp-server expõe o mesmo contrato como ferramentas, e tools/list é a versão legível por máquina desta página.