Skip to main content
POST
Crie fala a partir de texto usando uma voz do catálogo ou uma voz personalizada que lhe pertence. Usa os mesmos créditos de caracteres e limites de plano do aplicativo. Retorna um ID de histórico e uma URL temporária de download do áudio. Reutilize requestId para evitar uma segunda 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: tts: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: 128000.
string
obrigatório
Um ID de seleção de voz de voices_list, incluindo IDs clone: para vozes personalizadas salvas.Comprimento mínimo: 1. Comprimento máximo: 255.
string
Valor de texto.Valores aceitos: “text”, “pdf”. Valor padrão: “text”.
string
Valor de texto.Valores aceitos: “default”, “cheerful”, “calm”, “narrator”, “dramatic”, “whisper”, “energetic”. Valor padrão: “default”.
string
Valor de texto.Comprimento máximo: 300.
number
Valor numérico.Mínimo: 0.5. Máximo: 2. Valor padrão: 1.
string
Valor de texto.Comprimento máximo: 255.
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. Metadados da geração de fala concluída e uma URL temporária de download do MP3. O handler não retorna bytes de áudio.

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.
  • Escolha voice em voices_list. IDs de vozes de dublagem de dubbing_voices_list pertencem a uma biblioteca separada.
  • Os espaços nas extremidades do texto são removidos. O esquema aceita no máximo 128,000 caracteres; os planos atuais Beginner e Starter permitem 64,000 por geração, enquanto Creator e planos superiores permitem 128,000. O plano atual e os créditos de caracteres TTS disponíveis são verificados novamente antes da geração.
  • inputType tem text como padrão e pode ser text ou pdf. Mesmo com pdf, forneça o texto extraído em text; esta ação não aceita upload nem URL de PDF.
  • instructionPreset tem default como padrão e aceita default, cheerful, calm, narrator, dramatic, whisper e energetic. instructions é opcional e limitado a 300 caracteres após a remoção de espaços nas extremidades. speed tem 1 como padrão e varia de 0.5 a 2.
  • sourceFileName é um metadado opcional, limitado a 255 caracteres após remover espaços nas extremidades, e determina o nome do arquivo de download.
  • Uma requisição repetida bem-sucedida retorna o áudio salvo sem gerá-lo nem cobrá-lo novamente. As URLs são temporárias; use tts_download para obter um novo download.
  • 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