curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
"text": "Hello world.",
"spokenText": "Hello world.",
"voice": "933563129e564b19a115bedd57b7406a",
"voiceName": "Sarah",
"voiceSource": "catalog",
"inputType": "text",
"instructionPreset": "narrator",
"instructions": "Speak clearly and leave a short pause at the end.",
"speed": 1,
"sourceFileName": "launch-script.txt",
"characterCount": 12,
"durationSeconds": 1.5,
"previewEndIndex": null,
"createdAt": 1792152000000,
"updatedAt": 1792152000000,
"status": "success",
"audioUrl": "https://files.example.com/launch-script.mp3",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
}
}
Conversão de texto em fala
Consultar fala gerada
Consulte uma criação de fala que lhe pertence, incluindo seu roteiro, configurações de interpretação, URL temporária de áudio e alinhamento de palavras disponível.
POST
/
v1
/
actions
/
tts_get
curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
"text": "Hello world.",
"spokenText": "Hello world.",
"voice": "933563129e564b19a115bedd57b7406a",
"voiceName": "Sarah",
"voiceSource": "catalog",
"inputType": "text",
"instructionPreset": "narrator",
"instructions": "Speak clearly and leave a short pause at the end.",
"speed": 1,
"sourceFileName": "launch-script.txt",
"characterCount": 12,
"durationSeconds": 1.5,
"previewEndIndex": null,
"createdAt": 1792152000000,
"updatedAt": 1792152000000,
"status": "success",
"audioUrl": "https://files.example.com/launch-script.mp3",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
}
}
Consulte uma criação de fala que lhe pertence, incluindo seu roteiro, configurações de interpretação, URL temporária de áudio e alinhamento de palavras disponível.
Permissões necessárias:
POST https://api.voicecheap.ai/v1/actions/tts_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.
tts:read.
É 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
ID do histórico retornado por tts_generate ou tts_list.Padrão:
^(free-)?[0-9a-f]{64}$.Esquema de entrada completo
Esquema de entrada completo
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.
{
"type": "object",
"properties": {
"historyId": {
"type": "string",
"pattern": "^(free-)?[0-9a-f]{64}$",
"description": "History ID returned by tts_generate or tts_list."
}
},
"required": ["historyId"],
"additionalProperties": false
}
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.curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
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. Detalhes do histórico de fala pertencente à conta, roteiros completos editável e falado, configurações de interpretação, URL temporária de reprodução e quaisquer timestamps de palavras disponíveis.{
"data": {
"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
"text": "Hello world.",
"spokenText": "Hello world.",
"voice": "933563129e564b19a115bedd57b7406a",
"voiceName": "Sarah",
"voiceSource": "catalog",
"inputType": "text",
"instructionPreset": "narrator",
"instructions": "Speak clearly and leave a short pause at the end.",
"speed": 1,
"sourceFileName": "launch-script.txt",
"characterCount": 12,
"durationSeconds": 1.5,
"previewEndIndex": null,
"createdAt": 1792152000000,
"updatedAt": 1792152000000,
"status": "success",
"audioUrl": "https://files.example.com/launch-script.mp3",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
}
}
Campos do resultado
| Campo | Descrição |
|---|---|
data.historyId | ID do histórico de fala pertencente ao usuário: 64 caracteres hexadecimais minúsculos, opcionalmente com o prefixo free- para uma prévia do aplicativo. |
data.voice | O ID original de seleção TTS, incluindo clone:<UUID> para uma voz personalizada salva. |
data.voiceName | Nome de exibição salvo opcional da voz selecionada. |
data.voiceSource | Origem opcional da voz: catalog ou clone. |
data.inputType | Tipo de entrada original: text ou pdf. |
data.instructionPreset | Predefinição de entrega armazenada. |
data.sourceFileName | Nome opcional do arquivo original fornecido na geração. |
data.characterCount | Contagem de caracteres registrada para esta criação de fala. |
data.durationSeconds | Duração do áudio em segundos. |
data.createdAt | Horário de criação como um timestamp Unix em milissegundos. |
data.updatedAt | Horário da última atualização como uma marcação de tempo Unix em milissegundos. |
data.status | Itens de fala armazenados com sucesso usam success; tts_generate usa completed no resultado da geração. |
data.text | Roteiro armazenado completo e editável, incluindo as tags de controle de interpretação aceitas. |
data.spokenText | Roteiro armazenado com as tags de controle de interpretação aceitas removidas. |
data.instructions | Instruções personalizadas de interpretação armazenadas; vazio quando ausentes. |
data.speed | Velocidade de reprodução da fala armazenada; 1 quando ausente em registros antigos. |
data.previewEndIndex | Limite em caracteres da prévia disponível ou null para áudio completo. |
data.audioUrl | URL temporária reproduzível de áudio. |
data.wordAlignment | Timestamps das palavras ou null quando não há alinhamento disponível. |
data.wordAlignment[].text | Texto da palavra alinhada. |
data.wordAlignment[].startSeconds | Tempo de início da palavra em segundos. |
data.wordAlignment[].endSeconds | Horário de término da palavra em segundos. |
data.wordAlignment[].sourceStartCharacterIndex | Índice do caractere inicial em spokenText, após a remoção das tags de controle de interpretação. |
data.wordAlignment[].sourceEndCharacterIndex | Índice do caractere final em spokenText, após a remoção das tags de controle de interpretação. |
Notas da operação
- historyId deve ter 64 caracteres hexadecimais minúsculos, opcionalmente com o prefixo free-. Use o identificador retornado por tts_generate ou tts_list.
- Propriedades opcionais de registros antigos, como voiceName, voiceSource e sourceFileName, podem ser omitidas. instructions ausente tem uma string vazia como padrão, speed ausente tem 1 e previewEndIndex ausente tem null.
- wordAlignment pode ser null. Esta leitura carrega o alinhamento existente; use tts_align para preparar timestamps.
- Os índices de caracteres de origem em wordAlignment se referem a spokenText, que tem as tags de controle de interpretação removidas.
- audioUrl é temporária. Chame tts_get novamente para renovar a reprodução ou tts_download para obter um link de 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
| Status HTTP | Código | Significado ou recuperação |
|---|---|---|
| 400 | CREDENTIAL_IN_QUERY | Foram fornecidas credenciais em um parâmetro de consulta access_token ou api_key. Envie as credenciais nos cabeçalhos. |
| 400 | VALIDATION_ERROR | A entrada não corresponde ao esquema da ação; inspecione details para ver os erros dos campos. |
| 401 | API_KEY_EXPIRED | A chave de API expirou. |
| 401 | INVALID_API_KEY | Forneça uma chave de API válida e dentro do prazo de validade. |
| 401 | INVALID_CREDENTIAL | O cabeçalho Authorization está malformado ou entra em conflito com x-api-key. |
| 401 | MISSING_CREDENTIAL | Nenhuma credencial utilizável foi fornecida no cabeçalho, ou ela excedeu 4096 caracteres. |
| 401 | USER_NOT_FOUND | A conta da credencial não existe mais. |
| 403 | AMBIGUOUS_TEAM_API_KEY | O usuário da credencial pertence a mais de uma equipe, portanto o contexto de cobrança é ambíguo. |
| 403 | INSUFFICIENT_SCOPE | Conceda todas as permissões necessárias ou escolha outra credencial. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | Não foi possível verificar os limites de integração da conta. |
| 403 | SUBSCRIPTION_REQUIRED | Use uma assinatura paga ativa. |
| 403 | TEAM_OWNER_NOT_FOUND | Não foi possível encontrar a conta efetiva do proprietário da equipe. |
| 404 | TEXT_TO_SPEECH_HISTORY_NOT_FOUND | O item do histórico de fala não existe ou pertence a outra conta. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | Aguarde a renovação do limite mensal ou mude de plano. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Aguarde o prazo de Retry-After, quando presente, e aumente progressivamente o intervalo entre as tentativas. |
| 500 | INTERNAL_ERROR | Verifique o estado da requisição salva e o histórico do recurso antes de decidir repetir uma alteração. |
| 503 | SERVER_RESTARTING | O servidor está reiniciando. Tente novamente em breve e mantenha o mesmo identificador de requisição para uma alteração. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["tts:read"]
}
}
Esta página foi útil?

