> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Atualizar Voz do Agente

> Atualizar as configurações e ajustes de voz de um agente

# 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

<ParamField path="agent" type="string" required>
  O identificador único do agente de voz a ser atualizado.
</ParamField>

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Token Bearer para autenticação. Formato: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Deve ser definido como `application/json`
</ParamField>

## Corpo da requisição

<ParamField body="voice_id" type="string" required>
  ID do modelo de voz. Use [Listar Modelos de Voz](/api-reference/endpoints/list-voice-templates) para recuperar os IDs disponíveis.
</ParamField>

<ParamField body="conversation_speed" type="number" required>
  Multiplicador de velocidade de reprodução da conversa. Faixa: maior que `1`, menor que `2`.
</ParamField>

<ParamField body="who_speaks_first" type="string" required>
  Quem fala primeiro. Opções: `agent`, `user`.
</ParamField>

<ParamField body="ambient_background" type="string">
  Som de fundo ambiente para a conversa (ex: `office`, `cafe`, `quiet`). Opcional.
</ParamField>

<ParamField body="ambient_volume" type="number">
  Volume do som de fundo ambiente. Faixa: `0` (mudo) a `2` (alto). Padrão: `1`.
</ParamField>

<ParamField body="language" type="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.
</ParamField>

<ParamField body="similarity" type="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.
</ParamField>

<ParamField body="stability" type="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.
</ParamField>

## Exemplos de Requisição

<RequestExample>
  ```bash theme={null}
  # 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
    }'
  ```

  ```javascript theme={null}
  // 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);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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"
    }'
  ```

  ```javascript theme={null}
  // 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);
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "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": [.]
    }
  }
  ```
</ResponseExample>

### Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a operação foi bem-sucedida.
</ResponseField>

<ResponseField name="message" type="string" required>
  Mensagem de sucesso confirmando que a voz do agente foi atualizada.
</ResponseField>

<ResponseField name="data" type="object" required>
  O objeto do agente atualizado com as novas configurações de voz.

  <Expandable title="Objeto de Voz">
    <ResponseField name="id" type="string" required>
      Identificador único da voz.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Nome da voz.
    </ResponseField>

    <ResponseField name="label" type="string" required>
      Rótulo de exibição da voz.
    </ResponseField>

    <ResponseField name="stability" type="number">
      Configuração de estabilidade da voz (0.0 a 1.0).
    </ResponseField>

    <ResponseField name="similarity_boost" type="number">
      Configuração de similaridade da voz (0.0 a 1.0).
    </ResponseField>

    <ResponseField name="ambient_background" type="string">
      Configuração de fundo ambiente.
    </ResponseField>

    <ResponseField name="template" type="object">
      Informações do modelo de voz.
    </ResponseField>
  </Expandable>
</ResponseField>

## Respostas de erro

### Erro de Validação (422)

<ResponseExample>
  ```json theme={null}
  {
    "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."
      ]
    }
  }
  ```
</ResponseExample>

### 404 Não Encontrado

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Agent not found"
  }
  ```
</ResponseExample>

### 401 Não Autorizado

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthenticated."
  }
  ```
</ResponseExample>

### 403 Proibido

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "You are not authorized to perform this action."
  }
  ```
</ResponseExample>

## 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

<Info>
  **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.
</Info>

<Info>
  **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.
</Info>

## 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`