Pular para o conteúdo principal
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
  }'

{
  "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

​
agent
string
obrigatório
O identificador único do agente de voz a ser atualizado.

​
Cabeçalhos da requisição

​
Authorization
string
obrigatório
Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here
​
Content-Type
string
obrigatório
Deve ser definido como application/json

​
Corpo da requisição

​
voice_id
string
obrigatório
ID do modelo de voz. Use Listar Modelos de Voz para recuperar os IDs disponíveis.
​
conversation_speed
number
obrigatório
Multiplicador de velocidade de reprodução da conversa. Faixa: maior que 1, menor que 2.
​
who_speaks_first
string
obrigatório
Quem fala primeiro. Opções: agent, user.
​
ambient_background
string
Som de fundo ambiente para a conversa (ex: office, cafe, quiet). Opcional.
​
ambient_volume
number
Volume do som de fundo ambiente. Faixa: 0 (mudo) a 2 (alto). Padrão: 1.
​
language
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.
​
similarity
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.
​
stability
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 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"
  }'

​
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

​
success
boolean
obrigatório
Indica se a operação foi bem-sucedida.
​
message
string
obrigatório
Mensagem de sucesso confirmando que a voz do agente foi atualizada.
​
data
object
obrigatório
O objeto do agente atualizado com as novas configurações 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ódigoDescriçãoStatus HTTP
AGENT_NOT_FOUNDO agente especificado não existe404
INVALID_TOKENToken de autenticação inválido ou ausente401
UNAUTHORIZEDO usuário não tem permissão para atualizar este agente403
VOICE_NOT_FOUNDO modelo de voz especificado não existe404
VALIDATION_ERRORA validação dos dados da requisição falhou422

​
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

  1. Teste as alterações de voz - Sempre teste atualizações de voz antes de publicar
  2. Equilibre estabilidade e similaridade - Maior estabilidade para chamadas profissionais, maior similaridade para um toque pessoal
  3. Considere a velocidade da conversa - Velocidades mais rápidas para interações breves, mais lentas para tópicos complexos
  4. Combine o idioma com a voz - Garanta que o modelo de voz suporta o idioma especificado
  5. 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