Skip to main content
POST
Finalize suas partes enviadas e receba o fileKey que lhe pertence, usado pelas ações de geração.

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: projects: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.Formato: “uuid”. Padrão: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$.
array
obrigatório
Lista de valores. Consulte o esquema de entrada completo para ver a estrutura dos itens.Mínimo de itens: 1. Máximo de itens: 10000.
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

Uma primeira execução bem-sucedida retorna HTTP 200 com o resultado da operação em data. Uma repetição pode retornar o estado salvo da requisição. O exemplo mostra uma resposta aceita, não todos os campos opcionais. O fileKey concluído pertencente à conta e a URL de leitura da mídia. Passe fileKey para a próxima ação de geração ou voz.

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.
  • O prefixo de upload seleciona a permissão necessária. tools usa transcription:write, subtitles usa subtitles:write, projects usa projects:write e voices usa voices:write.
  • Para ferramentas, legendas e projetos, kind aceita transcription, video_to_srt, add_subtitles, animated_captions ou project. O kind selecionado determina os limites do fluxo de trabalho; o prefixo não impõe um kind.
  • O kind escolhido aplica seus próprios limites: transcription 200 MiB; video_to_srt e add_subtitles 300 MiB; animated_captions 250 MiB e somente áudio; project usa o limite de upload do plano (Beginner 5 GiB, Starter 10 GiB, Creator 20 GiB, Pro 30 GiB, Scale 40 GiB, Enterprise 60 GiB). Mídias independentes têm no máximo 2 horas. As legendas permitem 30 minutos no Beginner e 60 minutos nos planos públicos superiores, mais uma tolerância de 2 segundos no contêiner. A duração do projeto é de no máximo 2 horas, ou 3 horas no Enterprise.
  • Envie cada parte carregada exatamente uma vez com o ETag retornado por seu PUT. As partes são ordenadas por partNumber antes da finalização; os ETags podem incluir ou omitir as aspas ao redor.
  • Uma conclusão bem-sucedida remove a sessão ativa. Reutilize o mesmo requestId para recuperar seu resultado após a perda de uma resposta; não envie uma nova conclusão para a sessão já consumida.
  • Concluir um upload não consome a cota diária de geração. A geração separada determina o uso de mídia.

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