Skip to main content
POST
Crie uma prévia temporária de voz clonada a partir de 1–3 envios de áudio que lhe pertencem, com permissão explícita. Usa a cota de testes de clonagem do aplicativo. Salve a prévia selecionada antes que expire para mantê-la.

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: voices: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
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: 80.
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: 3.
boolean
obrigatório
Confirme que você tem permissão para clonar a voz da pessoa ouvida em todas as amostras.Valor obrigatório: true.
boolean
Valor booleano.Valor padrão: false.
string
Valor de texto.Comprimento máximo: 35. Padrão: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$.
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. Todas as prévias de voz ativas e não salvas e as cotas de criação atualizadas, incluindo o novo candidato de clonagem.

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

  • Use um requestId UUID v4 para esta alteração e reutilize-o com argumentos idênticos ao tentar novamente. Ações de longa duração retornam primeiro uma requisição running; este exemplo é o resultado concluído do handler, disponível em action_request_get.
  • Envie 1–3 amostras de áudio pertencentes à conta e use seus valores fileKey após a conclusão do envio. Os formatos de amostra compatíveis são MP3, WAV, M4A, OGG e Opus; cada arquivo deve ser não vazio e ter no máximo 20 MiB (20,971,520 bytes). URLs remotas e envios de outras contas são recusados.
  • As amostras devem totalizar no mínimo 10 segundos e no máximo 120 segundos de áudio legível. O padrão de trimToMaxDuration é false; defina-o como true para cortar proporcionalmente amostras que totalizem mais de 120 segundos.
  • hasPermission deve ser o booleano JSON true, confirmando a permissão para cada amostra. Um valor de string como “true” é rejeitado.
  • name deve conter 1–80 caracteres após a remoção dos espaços nas extremidades. O campo opcional language aceita um código de 2–3 letras com subtags opcionais e no máximo 35 caracteres.
  • Usa o único teste de prévia de clone permitido durante toda a existência da conta. Criar esta prévia não salva uma voz TTS reutilizável nem ocupa uma vaga de voz salva.
  • O novo candidato de clonagem tem kind: clone e dura 24 horas. Sua reprodução é limitada a aproximadamente 10 segundos.
  • A resposta inclui todas as prévias ativas não salvas. Use voices_preview_get para renovar a reprodução e voices_save_preview para manter o candidato escolhido em um plano pago.
  • language escolhe o roteiro da prévia quando existe um roteiro compatível; não é uma requisição para traduzir a amostra enviada.
  • O histórico de fala e as vozes personalizadas pertencem à conta autenticada. O faturamento da equipe não concede acesso à fala nem às vozes de outro membro.

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