# 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": [...]
  }
}

PUT

api

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. Você pode encontrá-lo em seu painel, na seção Agentes de Voz.

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.

Mostrar Objeto de Voz

string

obrigatório

Identificador único da voz.

name

string

obrigatório

Nome da voz.

label

string

obrigatório

Rótulo de exibição da voz.

stability

number

Configuração de estabilidade da voz (0.0 a 1.0).

similarity_boost

number

Configuração de similaridade da voz (0.0 a 1.0).

ambient_background

string

Configuração de fundo ambiente.

template

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

Atualizar Conhecimento do Agente Atualizar Configurações de Chamada do Agente

Primeiros Passos

Conceitos

Referência da API

Guias

Atualizar Voz do Agente

Atualizar Voz do Agente

Endpoint

Parâmetros de Caminho

Cabeçalhos da Requisição

Corpo da Requisição

Exemplos de Requisição

Resposta

Resposta de Sucesso (200 OK)

Campos da Resposta

Respostas de Erro

Erro de Validação (422)

404 Não Encontrado

401 Não Autorizado

403 Proibido

Códigos de Erro

Observações Importantes

Melhores Práticas

Endpoints Relacionados

Primeiros Passos

Conceitos

Referência da API

Guias

Documentation Index

​Atualizar Voz do Agente

​Endpoint

​Parâmetros de Caminho

​Cabeçalhos da Requisição

​Corpo da Requisição

​Exemplos de Requisição

​Resposta

​Resposta de Sucesso (200 OK)

​Campos da Resposta

​Respostas de Erro

​Erro de Validação (422)

​404 Não Encontrado

​401 Não Autorizado

​403 Proibido

​Códigos de Erro

​Observações Importantes

​Melhores Práticas

​Endpoints Relacionados

Atualizar Voz do Agente

Endpoint

Parâmetros de Caminho

Cabeçalhos da Requisição

Corpo da Requisição

Exemplos de Requisição

Resposta

Resposta de Sucesso (200 OK)

Campos da Resposta

Respostas de Erro

Erro de Validação (422)

404 Não Encontrado

401 Não Autorizado

403 Proibido

Códigos de Erro

Observações Importantes

Melhores Práticas

Endpoints Relacionados