# Request 1: Update voice with settings
curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-H "Content-Type: application/json" \
-d '{
"voice_id": "voice-template-uuid",
"language": "en-US",
"conversation_speed": 1.2,
"ambient_background": "office",
"who_speaks_first": "agent",
"similarity": 0.75,
"stability": 0.8
}'
// Request 1: Update voice with settings
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice', {
method: 'PUT',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
voice_id: "voice-template-uuid",
language: "en-US",
conversation_speed: 1.2,
ambient_background: "office",
who_speaks_first: "agent",
similarity: 0.75,
stability: 0.8
})
});
const result = await response.json();
console.log(result);
{
"success": true,
"message": "Agent voice updated successfully",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "SupportBot",
"label": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"language": "en-US",
"voice": {
"id": "voice-uuid",
"name": "Bianca",
"label": "Bianca Voice",
"stability": 0.8,
"similarity_boost": 0.75,
"ambient_background": "office",
"template": {
"id": "voice-template-uuid",
"name": "Bianca"
}
},
"initial_message": "Hello, how can I help you today?",
"interrupt_sensitivity": "medium",
"conversation_speed": 1.2,
"initial_message_delay": 0,
"ask_if_human_present_on_idle": false,
"direction": "inbound",
"who_speaks_first": "agent",
"current_status": "draft",
"is_sandbox": false,
"is_ready_to_publish": false,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:40:00Z",
"trainings": [.],
"actions": [.],
"phone_numbers": [.]
}
}
Agentes
Atualizar Voz do Agente
Atualizar as configurações e ajustes de voz de um agente
PUT
/
api
/
v1
/
agents
/
{agent_id}
/
voice
# Request 1: Update voice with settings
curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-H "Content-Type: application/json" \
-d '{
"voice_id": "voice-template-uuid",
"language": "en-US",
"conversation_speed": 1.2,
"ambient_background": "office",
"who_speaks_first": "agent",
"similarity": 0.75,
"stability": 0.8
}'
// Request 1: Update voice with settings
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice', {
method: 'PUT',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
voice_id: "voice-template-uuid",
language: "en-US",
conversation_speed: 1.2,
ambient_background: "office",
who_speaks_first: "agent",
similarity: 0.75,
stability: 0.8
})
});
const result = await response.json();
console.log(result);
{
"success": true,
"message": "Agent voice updated successfully",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "SupportBot",
"label": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"language": "en-US",
"voice": {
"id": "voice-uuid",
"name": "Bianca",
"label": "Bianca Voice",
"stability": 0.8,
"similarity_boost": 0.75,
"ambient_background": "office",
"template": {
"id": "voice-template-uuid",
"name": "Bianca"
}
},
"initial_message": "Hello, how can I help you today?",
"interrupt_sensitivity": "medium",
"conversation_speed": 1.2,
"initial_message_delay": 0,
"ask_if_human_present_on_idle": false,
"direction": "inbound",
"who_speaks_first": "agent",
"current_status": "draft",
"is_sandbox": false,
"is_ready_to_publish": false,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:40:00Z",
"trainings": [.],
"actions": [.],
"phone_numbers": [.]
}
}
Atualizar Voz do Agente
Atualiza a configuração de voz de um agente, incluindo modelo de voz, idioma, velocidade da conversa e outras configurações relacionadas à voz.Endpoint
PUT /api/v1/agents/{agent_id}/voice
Parâmetros de caminho
string
obrigatório
O identificador único do agente de voz a ser atualizado.
Cabeçalhos da requisição
string
obrigatório
Token Bearer para autenticação. Formato:
Bearer talq_your_environment_token_herestring
obrigatório
Deve ser definido como
application/jsonCorpo da requisição
string
obrigatório
ID do modelo de voz. Use Listar Modelos de Voz para recuperar os IDs disponíveis.
number
obrigatório
Multiplicador de velocidade de reprodução da conversa. Faixa: maior que
1, menor que 2.string
obrigatório
Quem fala primeiro. Opções:
agent, user.string
Som de fundo ambiente para a conversa (ex:
office, cafe, quiet). Opcional.number
Volume do som de fundo ambiente. Faixa:
0 (mudo) a 2 (alto). Padrão: 1.string
Código de idioma do agente (ex:
en-US, pt-BR). Opcional — enviado apenas ao alterar o idioma falado pelo agente. O modelo de voz deve suportar o idioma escolhido.number
Reforço de similaridade da voz. Faixa:
0.5 a 1.0. Obrigatório apenas para modelos de voz de alta fidelidade (o quality_tier do modelo de voz determina se este campo é aceito). Valores mais altos reforçam as características da voz.number
Estabilidade da voz. Faixa:
0.5 a 1.0. Obrigatório apenas para modelos de voz de alta fidelidade. Valores mais altos produzem saída mais consistente; valores mais baixos produzem saída mais expressiva.Exemplos de Requisição
# Request 1: Update voice with settings
curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-H "Content-Type: application/json" \
-d '{
"voice_id": "voice-template-uuid",
"language": "en-US",
"conversation_speed": 1.2,
"ambient_background": "office",
"who_speaks_first": "agent",
"similarity": 0.75,
"stability": 0.8
}'
// Request 1: Update voice with settings
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice', {
method: 'PUT',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
voice_id: "voice-template-uuid",
language: "en-US",
conversation_speed: 1.2,
ambient_background: "office",
who_speaks_first: "agent",
similarity: 0.75,
stability: 0.8
})
});
const result = await response.json();
console.log(result);
# Request 2: Update voice with basic settings
curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-H "Content-Type: application/json" \
-d '{
"voice_id": "basic-voice-uuid",
"language": "en-US",
"conversation_speed": 1.0,
"who_speaks_first": "user"
}'
// Request 2: Update voice with basic settings
const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice', {
method: 'PUT',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
voice_id: "basic-voice-uuid",
language: "en-US",
conversation_speed: 1.0,
who_speaks_first: "user"
})
});
const result = await response.json();
console.log(result);
Resposta
Resposta de Sucesso (200 OK)
{
"success": true,
"message": "Agent voice updated successfully",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "SupportBot",
"label": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"language": "en-US",
"voice": {
"id": "voice-uuid",
"name": "Bianca",
"label": "Bianca Voice",
"stability": 0.8,
"similarity_boost": 0.75,
"ambient_background": "office",
"template": {
"id": "voice-template-uuid",
"name": "Bianca"
}
},
"initial_message": "Hello, how can I help you today?",
"interrupt_sensitivity": "medium",
"conversation_speed": 1.2,
"initial_message_delay": 0,
"ask_if_human_present_on_idle": false,
"direction": "inbound",
"who_speaks_first": "agent",
"current_status": "draft",
"is_sandbox": false,
"is_ready_to_publish": false,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:40:00Z",
"trainings": [.],
"actions": [.],
"phone_numbers": [.]
}
}
Campos da Resposta
boolean
obrigatório
Indica se a operação foi bem-sucedida.
string
obrigatório
Mensagem de sucesso confirmando que a voz do agente foi atualizada.
object
obrigatório
O objeto do agente atualizado com as novas configurações de voz.
Mostrar Objeto de Voz
Mostrar Objeto de Voz
string
obrigatório
Identificador único da voz.
string
obrigatório
Nome da voz.
string
obrigatório
Rótulo de exibição da voz.
number
Configuração de estabilidade da voz (0.0 a 1.0).
number
Configuração de similaridade da voz (0.0 a 1.0).
string
Configuração de fundo ambiente.
object
Informações do modelo de voz.
Respostas de erro
Erro de Validação (422)
{
"success": false,
"message": "The given data was invalid.",
"errors": {
"voice_id": [
"The voice id field is required."
],
"language": [
"The language field is required."
],
"conversation_speed": [
"The conversation speed must be greater than 1 and less than 2."
],
"who_speaks_first": [
"The selected who speaks first is invalid."
],
"similarity": [
"The similarity must be at least 0.5 and less than 1."
],
"stability": [
"The stability must be at least 0.5 and less than 1."
]
}
}
404 Não Encontrado
{
"success": false,
"message": "Agent not found"
}
401 Não Autorizado
{
"success": false,
"message": "Unauthenticated."
}
403 Proibido
{
"success": false,
"message": "You are not authorized to perform this action."
}
Códigos de erro
| Código | Descrição | Status HTTP |
|---|---|---|
AGENT_NOT_FOUND | O agente especificado não existe | 404 |
INVALID_TOKEN | Token de autenticação inválido ou ausente | 401 |
UNAUTHORIZED | O usuário não tem permissão para atualizar este agente | 403 |
VOICE_NOT_FOUND | O modelo de voz especificado não existe | 404 |
VALIDATION_ERROR | A validação dos dados da requisição falhou | 422 |
Observações importantes
O status do agente será definido como rascunho. Após atualizar a voz do agente, ele será automaticamente definido como status “draft” e precisará ser publicado novamente para se tornar ativo.
As configurações de voz afetam a qualidade da chamada. Valores mais altos de estabilidade (próximos de 1.0) fornecem saída de voz mais consistente, enquanto valores mais altos de similaridade (próximos de 1.0) realçam as características da voz.
Melhores Práticas
- Teste as alterações de voz - Sempre teste atualizações de voz antes de publicar
- Equilibre estabilidade e similaridade - Maior estabilidade para chamadas profissionais, maior similaridade para um toque pessoal
- Considere a velocidade da conversa - Velocidades mais rápidas para interações breves, mais lentas para tópicos complexos
- Combine o idioma com a voz - Garanta que o modelo de voz suporta o idioma especificado
- Defina o fundo ambiente apropriado - Use “office” para chamadas comerciais, “quiet” para chamadas pessoais
Endpoints relacionados
- Obter Agente:
GET /api/v1/agents/{agent_id} - Atualizar Conhecimento do Agente:
PUT /api/v1/agents/{agent_id}/knowledge - Atualizar Configurações de Chamada do Agente:
PUT /api/v1/agents/{agent_id}/calling - Publicar Agente:
POST /api/v1/agents/{agent_id}/publish - Listar Agentes:
GET /api/v1/agents
Esta página foi útil?