Clipwright

API do Clipwright

Uma API HTTP que transforma um roteiro em um vídeo UGC com sincronização labial. Ela foi criada para ser dirigida por um agente: cada chamada é uma única solicitação JSON, cada recusa diz o que fazer em seguida e nada é publicado em lugar nenhum. Cada palavra desta página também é um arquivo markdown em https://clipwright.io/docs.md, e um contrato curto para agentes em https://clipwright.io/llms.txt.

Autenticação

Toda chamada vai para https://api.clipwright.io e carrega a chave em um cabeçalho:

Authorization: Bearer cw_your_key_here

• As chaves começam com cw_ e são mostradas uma vez, quando são emitidas. Mantemos apenas um resumo, então uma chave perdida é substituída, nunca recuperada.
• Emita e revogue chaves no painel em https://app.clipwright.io/api-keys. 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 a recebe como argumento.
• Uma chamada sem chave, ou com uma chave revogada, é recusada com 401 antes que qualquer cobrança seja feita.

03

Quanto custa

• make_ugc a partir de um roteiro simples: 30 créditos para cada segundo de vídeo finalizado, arredondado para o segundo inteiro.
• make_ugc com segmentos ou inserções: 10 créditos para cada segundo em que um rosto aparece na tela e pelo menos 400 créditos em um vídeo que entregamos. Segundos sem rosto não custam nada, e uma execução que não entrega nenhum arquivo não custa nada, mesmo quando o fornecedor já foi pago. O tempo de rosto é somado em todo o vídeo e arredondado uma vez, não por segmento. Esses campos exigem qualificação de formato longo na implantação; onde estiver desativado, eles são recusados pelo nome antes de qualquer cobrança.
• create_actor com qualidade média: 10 créditos para o retrato e 10 para cada formato adicional.
• create_actor com qualidade alta: 20 créditos para o retrato e 20 para cada formato adicional.
• Os créditos são comprados em pacotes: 1000 créditos por US$ 10,00, um único pagamento, sem assinatura.

Pergunte antes de gastar: o endpoint de cotação de qualquer habilidade não cobra nada. O valor da resposta difere por habilidade.

• make_ugc: a cotação é uma estimativa lida das 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 a conta pode ficar acima ou abaixo da cotação.
• create_actor: a cotação precifica cada formato que você pediu, que é o máximo que você pode pagar. Você é cobrado pelo retrato e pelas variantes realmente publicadas; um formato que não saiu é nomeado em warnings[] e não custa nada.

O custo de uma execução com falha também difere por habilidade:

• make_ugc a partir de um roteiro simples: uma execução que falhou depois que o trabalho de entrega chegou ao fornecedor é cobrada. Uma que falhou antes não custa nada, e o mesmo vale para uma que interrompemos, perdemos ou recusamos nós mesmos, mesmo quando o fornecedor já foi pago. No medidor de rosto, nenhuma falha é cobrada.
• create_actor: uma execução com falha não custa nada, mesmo quando o fornecedor já foi pago, porque nenhum ator chegou até você.

04

Endpoints

Endpoint	Custa créditos	O que faz
GET /health	não	Verificação de atividade da própria API. Responde sem chave.
GET /v1/voices	não	Vozes que você pode nomear em voice ou voice_id.
GET /v1/account	não	Saldo, dívidas e retenções da conta por trás da chave.
POST /v1/skills/make_ugc/quote	não	Precifica uma chamada make_ugc com esta entrada. Não cobra nada.
GET /v1/runs/{id}	não	Estado de uma execução de qualquer habilidade, seus avisos e seu url de vídeo.
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 habilidades e suas entradas, sem chave.
GET /v1/actors	não	Atores salvos na conta, com o id que make_ugc aceita.
DELETE /v1/actors/{id}	não	Esquece 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.
POST /v1/skills/create_actor/quote	não	Precifica 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 o url https que make_ugc e create_actor aceitam.

Uma execução de qualquer habilidade é lida de volta do mesmo lugar, GET /v1/runs/{id}, e passa por estes estados: queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

05

Habilidades e suas entradas

make_ugc. Inicie a geração de um vídeo UGC com sincronização labial. Dê um roteiro dentro do limite de texto do modelo de fala selecionado; o ator vem de actor_id (um ator salvo de list_actors) ou image, caso contrário, o ator padrão é usado. Formato e resolução seguem a solicitação e a fonte, com padrão de 1080x1920. As legendas são OPT-IN: pergunte ao usuário primeiro. Campos que o renderizador ainda não honra carregam uma nota NOT HONORED YET em sua própria descrição — leia-a em vez de adivinhar.

Chame quote_ugc antes de gerar e mostre o custo. Isso NÃO espera pelo vídeo: inicia a execução e retorna um run_id IMEDIATAMENTE. Você DEVE então consultar get_run com esse run_id até que o estado seja 'succeeded' (video_url) ou 'failed'. Uma execução 'failed' cujo trabalho pago do fornecedor ainda mantemos pode voltar para 'queued' e alcançar 'succeeded' mais tarde; sempre que isso acontecer, é nomeado em warnings[]. Passe attempt=2,3,… para iniciar deliberadamente uma NOVA execução para a mesma entrada (tentativa após uma falha).

Campo	Obrigatório	O que significa
script	opcional	As palavras que o ator diz; obrigatório a menos que segments forneça o texto falado. Segmentos e inserções ancoradas em texto exigem qualificação de formato longo no servidor. Limites de roteiro por modelo de fala: eleven_v3: 5000 caracteres; eleven_flash_v2_5: 10000 caracteres; eleven_turbo_v2_5: 10000 caracteres. A contagem inclui espaços, tags de áudio e marcas de ênfase; emojis podem contar como dois caracteres. Não há limite de contagem de palavras. Duração e preço são estimativas até serem medidos. Ênfase em russo: escreva a vogal tônica como maiúscula dentro de uma palavra minúscula ("потОм", "зАмок") e eleven_v3 a recebe como a marca de ênfase U+0301 ("пото́м"); uma marca digitada diretamente é mantida. Uma maiúscula no início de uma palavra permanece maiúscula, e uma palavra com uma segunda maiúscula ou uma consoante maiúscula interna (tudo em maiúsculas, "ВУЗы") é deixada como está. Uma única vogal maiúscula dentro de uma palavra é sempre lida como ênfase, então escreva "Яндекс Еда", não "ЯндексЕда". Diga aos usuários que escrevem em russo que eles podem marcar ênfase dessa forma. eleven_flash_v2_5 e eleven_turbo_v2_5 custam menos, mas leem mal as marcas de ênfase: maiúsculas chegam a eles inalteradas.
segments	opcional	Segmentos ordenados de ator e imagem; exige qualificação de formato longo no servidor, captions=false e 1080p. Mídia de imagem exige broll_policy=anyone explícito.
inserts	opcional	Inserções de imagem ancoradas em texto sobre narração completa, cada uma cobrindo cover_words palavras faladas a partir de sua âncora; exige qualificação de formato longo no servidor, captions=false, 1080p e broll_policy=anyone explícito.
person	opcional	NOT HONORED YET: person não é honrado ainda: esta solicitação usa o ator padrão; escolha actor_id de list_actors ou forneça image para selecionar um rosto diferente
actor_id	opcional	ID de ator Clipwright salvo de list_actors. Escolha actor_id, image ou person; não os combine. Sem voice ou voice_id, a voz segue o gênero do ator. Não combine com actor_gender.
image	opcional	Url https público da foto do ator (PNG, JPEG ou WebP, até 10 MB). Um arquivo em disco passa por upload_image (POST /v1/uploads) primeiro — passe o url que ele retorna. Uma fonte que não podemos usar — host privado ou de loopback, http, inacessível, com redirecionamento, acima de 10 MB ou não sendo um desses tipos de imagem — é recusada (unusable_source) antes de qualquer cobrança. Não detectamos o gênero do rosto: passe actor_gender ou voice, ou a voz masculina padrão é 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). Recusado com actor_id (seu gênero é conhecido) e sem image. Uma voice ou voice_id explícita vence e a resposta avisa que actor_gender não mudou nada.
name	opcional	NOT HONORED YET: name não é honrado ainda: não chega ao renderizador
broll_policy	opcional	SOMENTE ARMAZENADO: Política salva para B-roll: anyone permite pessoas incluindo o ator; no_actor exclui o ator; no_people exclui todas as pessoas, incluindo mãos. A geração de mídia segmentada está fechada. Esta configuração é somente armazenada e não tem efeito em vídeos somente de ator. A substituição da execução vence sobre o padrão do ator da conta; caso contrário, no_people.
captions	opcional	NOT HONORED YET: legendas solicitadas, mas não renderizadas neste protótipo (estágio-B)
caption_style	opcional	NOT HONORED YET: caption_style não é honrado: legendas não são renderizadas neste protótipo (estágio-B)
look	opcional	NOT HONORED YET: look não é honrado ainda: não chega ao renderizador
aspect_ratio	opcional	Formato de saída: 9:16 | 1:1 | 16:9. Omitido significa 9:16, e uma fonte de outra forma é ajustada para 9:16 com um aviso — passe-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 | 4k (lado curto 720 / 1080 / 2160 px). Omitido significa 1080p.
voice	opcional	Nome da voz de list_voices. Predefinições selecionadas: owner_ru_clone | sarah | george | eric | daria_ru_female (owner_ru_clone é a voz clonada em russo). A API recusa um nome que list_voices não retorna, antes de qualquer cobrança. Omitido significa 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. Mutuamente exclusivo com voice_id.
voice_id	opcional	ID de voz bruto do fornecedor (16–32 letras e dígitos) para uma voz fora do catálogo. Verificado preguiçosamente: um id desconhecido falha a execução, não a solicitação. Mutuamente exclusivo com voice.
tts_model	opcional	Modelo de fala: eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5. Omitido significa o modelo da predefinição escolhida (list_voices o mostra; toda predefinição fala eleven_v3) ou eleven_v3 para um voice_id bruto. eleven_v3 é o mais expressivo e o único que lê marcas de ênfase (uma vogal maiúscula dentro de uma palavra russa, "потОм", torna-se uma; veja script); eleven_flash_v2_5 e eleven_turbo_v2_5 são alternativas mais baratas para idiomas diferentes do russo. Limites de roteiro por modelo de fala: eleven_v3: 5000 caracteres; eleven_flash_v2_5: 10000 caracteres; eleven_turbo_v2_5: 10000 caracteres. A contagem inclui espaços, tags de áudio e marcas de ênfase; emojis podem contar como dois caracteres. Não há limite de contagem de palavras. Duração e preço são estimativas até serem medidos.
disclosure_overlay	opcional	Valores aceitos: true | false.
background	opcional	Valores aceitos: white | blur | contain.

create_actor. Crie um ator pessoal para esta conta a partir de palavras que descrevem um adulto fictício: um retrato 9:16 com exatamente um rosto, mais os outros formatos solicitados editados a partir dele. Retorna um run_id imediatamente; consulte get_run até 'succeeded' (created_actor.actor_id, então passe-o como actor_id para make_ugc) ou 'failed'. Cada imagem publicada é cobrada pelo preço que a cotação mostra; descrições recusadas e retratos inutilizáveis não custam nada. Quando a geração está desativada, a chamada falha com actor_generation_disabled.

Campo	Obrigatório	O que significa
description	obrigatório	Palavras que descrevem um adulto fictício: aparência, roupas, cenário. Nomear uma pessoa real ou uma semelhança com uma é recusado antes de qualquer cobrança (actor_prompt_refused).
gender	obrigatório	female | male. Define o gênero do ator e a voz padrão dos vídeos com este ator.
approximate_age	obrigatório	Idade aproximada em anos, de 18 a 90: atores são adultos.
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, significa todos os três. Formatos que falham na verificação de identidade não são cobrados e são nomeados nos avisos.
quality	opcional	Qualidade da imagem: medium | high. Se omitido, significa medium. O preço por imagem depende disso; a cotação mostra antes de qualquer cobrança.

O formato de saída segue a solicitação e a fonte. Os formatos suportados são 9:16, 1:1, 16:9 e resoluções 720p, 1080p, 4k; silêncio significa 1080p em 9:16.

06

Iniciando uma execução

Uma chamada paga carrega um cabeçalho além da chave: Idempotency-Key. POST /v1/skills/make_ugc/run e POST /v1/skills/create_actor/run exigem isso, e uma chamada sem ele é recusada com 400 idempotency_key_required antes de qualquer cobrança.

• Você escolhe a chave, e ela é a única coisa que distingue uma nova tentativa de um segundo pedido. Qualquer string única serve; guarde-a enquanto puder reenviar a chamada.
• A mesma chave com o mesmo corpo retorna a execução já iniciada e não cobra nada uma segunda vez. É isso que torna uma nova tentativa comum segura.
• 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á gasta.
• Para iniciar deliberadamente uma nova execução na mesma entrada — uma nova tentativa após uma falha — envie uma nova chave. A execução que você já pagou permanece onde está.
• @clipwright/sdk e @clipwright/mcp-server constroem a chave para você a partir do cliente e da entrada, e transformam attempt=2, 3 … em uma nova. Via HTTP puro, a chave é sua para escolher.

07

Quando uma chamada falha

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

Recusa	HTTP	Repetir a mesma chamada?	O que fazer
rate_limited	429	sim, após a espera	Pressão de volta, não um erro: a resposta nomeia os segundos de espera, em Retry-After e no corpo.
server_error	500, 502, 503	sim, após a espera	A falha está no lado do servidor. Não inicie uma segunda execução com uma nova chave de idempotência: a mesma chamada é a nova tentativa.
insufficient_credits	402	não, dá a mesma resposta	Pare e informe à pessoa o saldo e o preço; ambos estão no corpo. Repetir não pode mudar nenhum dos dois.
debt_outstanding	402	não, dá a mesma resposta	Pare. Comprar créditos quita a dívida antes que qualquer coisa chegue ao saldo, e isso remove o bloqueio.
not_admitted	403	não, dá a mesma resposta	Pare. A conta não tem acesso beta; nem uma nova tentativa nem uma compra mudam isso. Pergunte ao operador.
client_error	400, 401, 404, 409, 413, 415	não, dá a mesma resposta	Pare. A própria solicitação foi recusada: leia a mensagem, corrija a chamada e envie novamente.

Estes são todos os códigos que a API coloca em error.code. Um código que você nunca viu antes ainda segue sua linha 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
• aspect_conflict
• debt_outstanding
• idempotency_key_required
• idempotency_key_reused
• insufficient_credits
• internal_error
• invalid_image
• invalid_request
• malformed_body
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• rejected_field
• script_encoding_lost
• unauthorized
• unknown_field
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upstream_error

08

Limites

• 60 solicitações pagas e 300 gratuitas por 60 segundos. A janela é contada por conta, não por chave, então chaves extras não compram mais taxa de transferência.
• 3 renderizações rodam ao mesmo tempo por conta; o resto fica na fila e não é recusado.
• Uma recusa por limite de taxa nomeia os segundos de espera em Retry-After e no corpo. Respeite o maior dos dois.
• 49 inserções por clipe, e no máximo 6 aparições do ator entre elas. Ambos são contados a partir dos índices de palavras que você envia, então uma entrada que pede mais é recusada antes de qualquer pagamento.
• cover_words diz quantas palavras faladas uma inserção cobre, contadas a partir da primeira palavra de sua âncora. A inserção termina onde a primeira palavra descoberta começa, então duas inserções cuja cobertura se encontra são adjacentes e não deixam nenhum plano do ator entre elas.
• A parcela de palavras que você deixa descoberta decide a parcela do clipe que mostra um rosto, e ela não se move com a velocidade da voz. O comprimento das palavras varia: em um roteiro de 560 palavras, pedir 19% entregou 16 a 22 em novecentas e noventa e sete execuções simuladas de mil, e permaneceu dentro de 15 a 24 em cinquenta mil. Esses números foram medidos na voz deste perfil e nesse comprimento; um roteiro mais curto espalha mais, e uma voz diferente os move.
• Duas escolhas de uma palavra mudam o preço, não apenas a aparência. Uma inserção ancorada na palavra 0 possui o silêncio antes da primeira palavra; ancorada na palavra 1, deixa uma aparição extra do ator, e cada aparição é um trabalho pago separado. A cobertura que alcança a última palavra leva o clipe ao fim e remove a aparição final da mesma forma.
• Uma cotação relata a parcela como estimatedFaceWordShare. Leia esse campo; não divida estimatedFaceSeconds por estimatedTotalDurationSec. Esses dois respondem a perguntas diferentes — o primeiro é a reserva que mantemos no extremo lento da faixa de fala, o segundo é quanto tempo o clipe deve durar — e sua razão não é a parcela de nada.

09

O que esta API nunca fará

• Publicar qualquer coisa. Retornamos um arquivo e um link assinado; para onde ele vai é sua decisão.
• Cancelar uma execução iniciada. Não há endpoint para isso: uma vez que o fornecedor tem o trabalho, pará-lo do nosso lado não o desfaria.
• Aceitar estes campos: character, broll_url, webhook_url. Eles são recusados pelo nome antes de qualquer cobrança, não aceitos e silenciosamente ignorados.
• Mudar o formato ou a resolução que você pediu sem dizer. Uma incompatibilidade é ou ajustada com um aviso ou recusada antes da chamada paga.
• Chamar você de volta. Não há webhooks: leia a execução com GET /v1/runs/{id}.
• Mostrar uma chave uma segunda vez, ou recuperar uma de um backup.

10

Também vale a pena saber

• Avisos, não silêncio. Qualquer coisa que não pudemos honrar volta em warnings[] na mesma execução, nomeada. Um parâmetro nunca desaparece sem uma linha sobre ele.
• Um servidor MCP. @clipwright/mcp-server expõe o mesmo contrato como ferramentas, e seu tools/list é a forma legível por máquina desta página.