curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{}'
const input = {};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_list', {
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/voices_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"voices": [
{
"accent": "original",
"id": "clone:33333333-3333-4333-8333-333333333333",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
{
"id": "933563129e564b19a115bedd57b7406a",
"name": "Sarah",
"accent": "english",
"gender": "female",
"style": "conversational",
"previewFileName": "sarah-en.mp3",
"source": "catalog"
}
],
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
},
"voicePreviews": [
{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "clone",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/narrator-preview.mp3",
"expiresAt": 1792238400000,
"durationSeconds": 10
}
],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
}
}
}
Vozes de fala
Listar vozes e prévias de voz
Liste as vozes de fala disponíveis, suas vozes personalizadas salvas, prévias reproduzíveis ainda válidas e suas cotas de criação de vozes.
POST
/
v1
/
actions
/
voices_list
curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{}'
const input = {};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_list', {
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/voices_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"voices": [
{
"accent": "original",
"id": "clone:33333333-3333-4333-8333-333333333333",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
{
"id": "933563129e564b19a115bedd57b7406a",
"name": "Sarah",
"accent": "english",
"gender": "female",
"style": "conversational",
"previewFileName": "sarah-en.mp3",
"source": "catalog"
}
],
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
},
"voicePreviews": [
{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "clone",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/narrator-preview.mp3",
"expiresAt": 1792238400000,
"durationSeconds": 10
}
],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
}
}
}
Liste as vozes de fala disponíveis, suas vozes personalizadas salvas, prévias reproduzíveis ainda válidas e suas cotas de criação de vozes.
Permissões necessárias:
POST https://api.voicecheap.ai/v1/actions/voices_list
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.
voices: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
Envie um objeto JSON vazio. Esta ação não possui campos de entrada.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": {},
"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/voices_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{}'
const input = {};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_list', {
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/voices_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={},
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. Vozes disponíveis do catálogo TTS e vozes personalizadas salvas pertencentes à conta, cota de vagas salvas, prévias ativas não salvas e cotas de criação de voz.{
"data": {
"voices": [
{
"accent": "original",
"id": "clone:33333333-3333-4333-8333-333333333333",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
{
"id": "933563129e564b19a115bedd57b7406a",
"name": "Sarah",
"accent": "english",
"gender": "female",
"style": "conversational",
"previewFileName": "sarah-en.mp3",
"source": "catalog"
}
],
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
},
"voicePreviews": [
{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "clone",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/narrator-preview.mp3",
"expiresAt": 1792238400000,
"durationSeconds": 10
}
],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
}
}
}
Campos do resultado
| Campo | Descrição |
|---|---|
data.voices | Vozes TTS salvas pertencentes ao usuário, seguidas das vozes disponíveis no catálogo. |
data.voices[].id | ID de seleção TTS para tts_generate; valores personalizados usam clone:<UUID>. |
data.voices[].name | Nome de exibição da voz. |
data.voices[].source | catalog ou clone. |
data.voices[].accent | Sotaque da voz; original para vozes personalizadas. |
data.voices[].gender | Gênero opcional da voz do catálogo. |
data.voices[].style | Estilo opcional de interpretação da voz do catálogo. |
data.voices[].previewFileName | Nome opcional do arquivo de prévia incluído no catálogo; não é uma URL de download. |
data.voices[].previewUrl | URL reproduzível opcional; as URLs de vozes personalizadas são temporárias. |
data.cloneUsage.canClone | Indica se o plano atual permite vozes TTS personalizadas salvas; inspecione remaining para ver as vagas disponíveis. |
data.cloneUsage.limit | Limite do plano para vagas de vozes TTS personalizadas salvas. |
data.cloneUsage.used | Vagas ocupadas de vozes TTS, incluindo criações reservadas. |
data.cloneUsage.remaining | Vagas disponíveis de vozes TTS salvas. |
data.voicePreviews | Todas as prévias atualmente ativas e não salvas desta conta, incluindo candidatos de requisições anteriores. |
data.voicePreviews[].id | UUID v4 da prévia usado por voices_preview_get e voices_save_preview. |
data.voicePreviews[].kind | clone ou design. |
data.voicePreviews[].name | Nome de exibição da prévia; candidatos criados por design acrescentam um número ao nome solicitado. |
data.voicePreviews[].previewUrl | URL temporária de áudio reproduzível. Solicite uma nova URL com voices_preview_get enquanto a prévia permanecer ativa. |
data.voicePreviews[].expiresAt | Expiração da prévia como timestamp Unix em milissegundos. |
data.voicePreviews[].durationSeconds | Duração do áudio de prévia em segundos. |
data.creationUsage.cloneTrial | Cota vitalícia de teste de prévia de clonagem com limit, used e remaining. |
data.creationUsage.design | Cota diária de design de voz com limit, used, remaining e resetsAt em milissegundos Unix. |
data.creationUsage.previewExpiresAfterHours | Tempo de vida de uma prévia não salva em horas, atualmente 24. |
Notas da operação
- O catálogo do exemplo está abreviado. A ação retorna a biblioteca TTS disponível, com as vozes personalizadas salvas antes das entradas do catálogo.
- Use voices[].id em tts_generate. As vozes salvas usam clone:<UUID>; os IDs do catálogo são opacos. Esses IDs são separados de dubbing_voices_list.
- As entradas do catálogo incluem accent, gender, style e previewFileName; previewUrl é opcional. As entradas personalizadas salvas incluem accent: original, source: clone e um previewUrl temporário.
- canClone indica se o plano permite vozes TTS personalizadas salvas; remaining indica vagas livres. Criações reservadas podem contar em used.
- voicePreviews inclui apenas candidatos pertencentes ao usuário, não salvos, prontos e não expirados. Uma prévia dura 24 horas; sua URL reproduzível pode expirar antes.
- cloneTrial é uma cota vitalícia de uma prévia de clonagem. Os planos pagos têm cinco requisições de criação por dia UTC; cada criação bem-sucedida gera dois candidatos. creationUsage informa a cota atual e o horário de renovação.
- 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 | USER_NOT_FOUND | A conta autenticada não existe mais. |
| 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": ["voices:read"]
}
}
Esta página foi útil?

