Skip to main content
POST
Adicione um modelo de legendas dinâmicas selecionado a um vídeo traduzido ou com sincronização labial concluído. Usa a cota normal do plano e os créditos de mídia habituais. Consulte projects_get.

Autenticação e permissões

string
obrigatório
Envie uma chave de API VoiceCheap neste cabeçalho. Authorization: Bearer com a mesma chave de API também é aceito. Tokens de acesso OAuth são aceitos apenas pelo MCP, não por este endpoint REST.
Permissões necessárias: subtitles:write. É necessária uma assinatura paga ativa. As permissões não alteram funções na equipe, propriedade dos recursos, créditos de mídia ou limites do plano.

Parâmetros

string
obrigatório
Valor de texto.Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: ^[^/\\]+$.
string
obrigatório
Valor de texto.Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: ^[^/\\]+$.
string
obrigatório
Valor de texto.Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: ^[^/\\]+$.
string
obrigatório
Valor de texto.Valores aceitos: “Sara”, “Daniel”, “Dan 2”, “Hormozi 4”, “Dan”, “Devin”, “Tayo”, “Ella”, “Tracy”, “Luke”, “Hormozi 1”, “Hormozi 2”, “Hormozi 3”, “Hormozi 5”, “Leon”, “Ali”, “Beast”, “Maya”, “Karl”, “Iman”, “Umi”, “David”, “Noah”, “Gstaad”, “Malta”, “Nema”, “Seth”, “William”.
string
Valor de texto.Valores aceitos: “translated”, “lip-synced”. Valor padrão: “translated”.
boolean
Valor booleano.Valor padrão: false.
boolean
Valor booleano.Valor padrão: false.
number
Valor numérico.Mínimo: 0. Máximo: 100. Valor padrão: 0.
string
Valor de texto.Valores aceitos: “natural”, “fast”, “extra-fast”.
boolean
Valor booleano.
string
Opcional na camada de transporte: o servidor insere um identificador antes da validação quando ele é omitido. Forneça seu próprio UUID v4 estável para recuperar com segurança uma resposta perdida.Formato: “uuid”. Padrão: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
O JSON Schema abaixo preserva os nomes exatos dos campos, tipos aninhados, valores padrão, limites e valores aceitos expostos pela descoberta. Regras adicionais entre campos são listadas nas notas da operação.

Idempotência

Use um UUID v4 em requestId ou no cabeçalho HTTP Idempotency-Key para cada alteração. Reutilize o mesmo identificador e argumentos idênticos após uma falha de rede. Se ambos forem fornecidos, devem ser iguais. Repetir uma requisição salva não repete a operação nem consome outra chamada mensal. Requisições com falha ou interrompidas não são reiniciadas automaticamente. Qualquer alteração pode retornar HTTP 202 quando uma nova tentativa encontra a mesma requisição ainda em execução, mesmo que a primeira execução normalmente seja síncrona. Se a execução foi concluída, mas resultStored é false, uma nova tentativa retorna HTTP 200 com o estado salvo da requisição em vez do resultado original. Recupere a saída pela ação de histórico, resultado ou download do domínio correspondente.

Exemplos de requisição

Substitua os identificadores de recursos e as chaves de mídia dos exemplos pelos valores retornados para sua conta. Mantenha o identificador da requisição ao tentar novamente a mesma alteração.

Resposta

Esta operação retorna HTTP 202 enquanto está em execução. Salve requestId e consulte action_request_get com esse identificador e o nome da operação original. Os estados de consulta são running, completed, failed e interrupted. Um resultado concluído pode apontar para um processamento de mídia separado; continue com a ação de status ou de saída específica da operação. Retorna os identificadores do projeto, trabalho e versão selecionados com status de processamento após admitir legendas dinâmicas.

Campos do resultado

Recuperar e consultar esta requisição

Use o mesmo identificador mesmo após perder a conexão. Se resultStored for false, recupere a saída pela ação correspondente de histórico, resultado ou download. Nunca inicie uma segunda geração apenas para verificar o progresso.
HTTP 200

Notas da operação

  • templateName é o nome de um modelo compatível. videoSource usa translated por padrão; lip-synced seleciona o vídeo armazenado de sincronização labial concluído mais recente. URLs de mídia do chamador não são aceitas.
  • A versão selecionada deve estar concluída e o vídeo selecionado deve estar disponível. MP4 e MOV são compatíveis; a duração armazenada do projeto deve ser de no máximo 2 horas e seu tamanho armazenado em bytes, de no máximo 2 GiB.
  • magicZooms e magicBrolls usam false por padrão; magicBrollsPercentage usa 0 por padrão. O removeSilencePace opcional aceita natural, fast ou extra-fast; removeBadTakes é um booleano.
  • O idioma vem do trabalho de idioma autorizado. Aplicam-se a cota habitual do plano e as verificações de créditos de mídia; uma tradução pode executar novamente as legendas dinâmicas apenas uma vez.
  • Esta é uma ação de longa duração. Consulte action_request_get periodicamente primeiro para aguardar a conclusão do processador e depois projects_get.translations[].dynamicSubtitles para obter inProgress, videoUrl e errorMessage. projects_status não expõe esse estado das legendas dinâmicas.

Uso

Cada chamada bem-sucedida consome uma chamada mensal da API/MCP. Os créditos de mídia e as cotas de geração da própria operação também se aplicam.

Erros