Skip to main content
POST
Incorpore as legendas SRT fornecidas a um vídeo público do YouTube e salve o resultado.

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áximo: 2048. Formato: “uri”.
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}$.
string
obrigatório
Valor de texto.Comprimento mínimo: 1. Comprimento máximo: 2097152.
string
Valor de texto.Comprimento mínimo: 2. Comprimento máximo: 60.
object
Objeto JSON. Consulte o esquema de entrada completo para ver os campos aninhados.
object
Objeto JSON. Consulte o esquema de entrada completo para ver os campos aninhados.
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. Uma referência salva de resultado de renderização de legendas do YouTube. O JSON completo contém srt, sourceSrt, subtitledVideoUrl e detectedLanguage opcional.

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

  • Requer uma assinatura paga e a permissão da ação. O plano pessoal de ferramentas do usuário executor é verificado novamente na execução; as ferramentas salvas e as referências de envio pertencem a esse usuário, inclusive quando a credencial está associada a uma equipe.
  • Uma ação bem-sucedida usa uma chamada mensal compartilhada de API/MCP. Beginner permite 500, Starter 5,000 e Creator 25,000 chamadas/mês; Pro, Scale e Enterprise não têm teto mensal. Os limites por minuto ainda se aplicam: 30, 60, 120, 180, 300 e 600, respectivamente. As cotas de geração das ferramentas são separadas.
  • Use um requestId UUID v4 ou um cabeçalho Idempotency-Key idêntico e mantenha a mesma ação, ID e argumentos nas novas tentativas. Uma repetição em cache não usa outra chamada mensal.
  • Esta é uma ação assíncrona. O resultado inicial do transporte é uma requisição running com pollAction; consulte action_request_get periodicamente com esta operação e o requestId original. O resultado da operação concluída mostrado aqui é uma referência compacta à saída salva, não o corpo gerado.
  • A saída completa é salva sob a propriedade autenticada em armazenamento criptografado, independentemente do cache limitado de consulta de ações. Chame o getAction retornado com resultId e includeContent: true para obter JSON estruturado, ou downloadAction com resultId para obter texto JSON. listAction oferece uma forma de recuperação quando apenas a requisição original é conhecida.
  • O JSON salvo é limitado a 32 MiB. Os metadados nunca expõem sua chave de criptografia do armazenamento nem uma URL não autenticada de download da transcrição.
  • Uma geração bem-sucedida confirma o uso de uma unidade da cota pessoal da ferramenta. Uma geração com falha normalmente libera a reserva da ferramenta. Quando a persistência da saída é incerta, inspecione a mesma requisição e o histórico de resultados salvos antes de gerar novamente; o servidor mantém a reserva para impedir uso duplicado.
  • Os planos superiores sem teto mensal de integração ainda têm as cotas diárias específicas de cada ferramenta e os limites de mídia abaixo. Essas ações independentes usam a cota da ferramenta em vez de minutos de dublagem ou caracteres TTS.
  • Forneça uma URL pública HTTPS de vídeo do YouTube e SRT válido em srtContent. Embora o esquema da ação marque srtContent como opcional, o renderizador atual do YouTube o valida incondicionalmente e retorna 400 SRT_EMPTY quando omitido. Este handler não gera legendas do YouTube automaticamente.
  • O vídeo importado do YouTube deve ter no máximo 2 horas, e o arquivo montado deve ter no máximo 300 MiB. A resolução da importação segue o plano do autor da ação.
  • Cota diária por ferramenta: Beginner 5, Starter 15, Creator 30, Pro 60, Scale 100 e Enterprise 100 gerações bem-sucedidas. Ela é compartilhada com a ferramenta web correspondente e usa a janela de renovação da ferramenta da conta.
  • Compartilha o limite diário de adição de legendas com subtitles_burn. Uma renderização usa uma geração mesmo quando o SRT é fornecido.
  • Nenhum fileKey enviado anteriormente é usado. O vídeo renderizado é armazenado separadamente; seu histórico salvo de incorporação de legendas pode renovar a URL temporária de download.

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