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

# Referência da API

> Todos os endpoints disponíveis para quem integra com o Symphony usando chave de API, com parâmetros, exemplos e respostas.

## O que é

Esta é a referência de **todos os endpoints disponíveis para quem integra com o Symphony usando chave de API**. Cada endpoint traz o método, o caminho, os parâmetros, um exemplo de chamada e o formato da resposta.

Se é a sua primeira vez, comece por [Conectar via API](/desenvolvedores/api/conectar-api). Para entender **como combinar** esses endpoints num projeto real, veja [Criando projetos com a API](/desenvolvedores/api/projetos-com-a-api).

## 1. Antes de começar

### Endereço base

```
https://symphony.fcamara.com
```

Para testes, veja [Ambientes e suporte](/desenvolvedores/api/ambientes-e-suporte).

### Headers

Todos os endpoints desta página, exceto os da seção **10. Status do serviço**, exigem:

| Header | Valor | Quando |
| - | - | - |
| `Authorization` | `Bearer sk-...` | Sempre |
| `X-Enterprise-Id` | ID da sua empresa | Sempre |
| `Content-Type` | `application/json` | Em requisições com corpo JSON |

Não envie cookies nem token CSRF. Eles não são necessários com chave de API.

### O que a sua chave pode fazer

A chave tem **exatamente os mesmos acessos da sua conta**: os mesmos modelos, agentes, bases de conhecimento, fluxos, permissões e limite de consumo. Se você não consegue fazer algo pela interface, também não vai conseguir pela API.

Algumas ações dependem de permissão dada pelo administrador da empresa (por exemplo, criar bases de conhecimento). Consulte as suas em `GET /api/v1/users/permissions`.

### Convenções

* **Datas** são números inteiros em *epoch* (segundos desde 01/01/1970, UTC), salvo indicação contrária.
* **IDs** são strings. Copie-os exatamente como vieram.
* **Paginação por cursor:** endpoints de lista devolvem `{ "items": [...], "next_cursor": "..." }`. Para buscar a próxima página, repita a chamada com `?cursor=<next_cursor>`. Quando `next_cursor` vier `null`, acabou. O `limit` aceita de 1 a 200.
* **Erros** seguem um formato único, descrito em [Erros e limites](/desenvolvedores/api/erros-e-limites).

## 2. Conta e chave de API

### `GET /api/v1/auths/api_key`

Retorna a sua chave de API atual.

```json theme={null}
{ "api_key": "sk-1a2b3c..." }
```

Retorna `404` se você ainda não gerou nenhuma chave.

### `POST /api/v1/auths/api_key`

Gera uma nova chave. **A chave anterior para de funcionar na hora.**

```json theme={null}
{ "api_key": "sk-9z8y7x..." }
```

Retorna `403` se a geração de chaves estiver desativada no ambiente.

### `DELETE /api/v1/auths/api_key`

Revoga a sua chave. Retorna `true`. Depois disso, nenhuma chamada com ela funciona.

<Note>
  Gerar e revogar normalmente é feito pela interface (**Configurações → Conta → Chaves de API**). Estes endpoints existem para quem precisa automatizar a rotação.
</Note>

### `GET /api/v1/auths/`

Retorna os dados da conta dona da chave.

```json theme={null}
{
  "id": "b7c1...",
  "email": "ana.souza@empresa.com",
  "name": "Ana Souza",
  "role": "user",
  "enterprise_id": "fcamara-0000-0000-0000-000000000001",
  "permissions": { "workspace": { ... }, "chat": { ... }, "features": { ... } }
}
```

<Note>
  A resposta também traz os campos `token`, `token_type` e `expires_at`. Eles servem para a sessão do navegador e **não são necessários** para quem usa chave de API.
</Note>

### `GET /api/v1/users/permissions`

Retorna o que a sua conta pode fazer.

```json theme={null}
{
  "workspace": {
    "models": false,
    "knowledge": true,
    "prompts": true,
    "tools": false,
    "workflows": true
  },
  "chat": {
    "file_upload": true,
    "stt": true,
    "tts": true
  },
  "features": {
    "web_search": true,
    "image_generation": false,
    "code_interpreter": true
  }
}
```

| Grupo | O que controla |
| - | - |
| `workspace` | Se você pode **criar** agentes (`models`), bases de conhecimento (`knowledge`), prompts, ferramentas e fluxos (`workflows`) |
| `chat` | Recursos da conversa: envio de arquivos (`file_upload`), transcrição (`stt`), fala (`tts`) |
| `features` | Recursos ligados pelo campo `features` do chat: busca na web, geração de imagem e interpretador de código |

### `GET /api/v1/consumption/me`

Retorna o seu consumo do mês e a situação do seu limite.

```json theme={null}
{
  "userId": "b7c1...",
  "period": "monthly",
  "tokensUsed": 182340,
  "cost": 12.47,
  "executions": 318,
  "costLimit": 50.0,
  "defaultCostLimit": 50.0,
  "isConsumptionBlocked": false,
  "byModel": [ ... ],
  "byAgent": [ ... ],
  "timeseries": [ ... ],
  "lastConsumptionAt": 1760533200000,
  "peakHour": 15,
  "status": "ok"
}
```

| Campo | Significado |
| - | - |
| `cost` / `costLimit` | Gasto no mês e teto mensal da sua conta |
| `status` | `ok` (dentro do limite), `warning` (perto do limite), `reached` (limite atingido) ou `blocked` (acesso bloqueado pelo administrador) |
| `byModel`, `byAgent` | Consumo detalhado por modelo e por agente |
| `timeseries` | Consumo por dia |
| `lastConsumptionAt` | Momento do último uso, em **milissegundos** |

Com `status` em `reached` ou `blocked`, as chamadas de chat retornam `402`. Use este endpoint antes de lotes grandes.

## 3. Modelos e agentes

### `GET /api/models`

Lista os modelos **e agentes** que a sua conta pode usar na empresa informada em `X-Enterprise-Id`.

```bash theme={null}
curl https://symphony.fcamara.com/api/models \
  -H "Authorization: Bearer sk-..." \
  -H "X-Enterprise-Id: SEU_ID_DE_EMPRESA"
```

```json theme={null}
{
  "data": [
    { "id": "azure.gpt-5-chat", "name": "Azure gpt-5-chat", "owned_by": "openai" },
    {
      "id": "fc-code-assistant",
      "name": "Code Vader",
      "info": { "base_model_id": "azure.gpt-5-chat" }
    }
  ]
}
```

* O `id` é o valor que vai no campo `model` do chat.
* Itens com `info.base_model_id` são **agentes**: já vêm com prompt, bases e ferramentas configurados na plataforma.
* A lista já vem filtrada pelo que você pode usar. Modelos desativados ou não compartilhados com você não aparecem.

## 4. Chat

### `POST /api/chat/completions`

Envia mensagens para um modelo ou agente e recebe a resposta. **Compatível com a API de chat completions da OpenAI.**

**Campos obrigatórios**

| Campo | Tipo | Descrição |
| - | - | - |
| `model` | string | `id` vindo de `GET /api/models` |
| `messages` | array | Lista de `{ "role": "...", "content": "..." }`, com `role` igual a `system`, `user`, `assistant` ou `tool` |

**Campos opcionais: geração**

| Campo | Tipo | Descrição |
| - | - | - |
| `stream` | boolean | `true` devolve a resposta em tempo real (Server-Sent Events). Padrão `false` |
| `stream_options` | object | `{ "include_usage": true }` para receber a contagem de tokens no streaming |
| `temperature` | number | Criatividade da resposta |
| `top_p` | number | Controle alternativo de aleatoriedade |
| `max_tokens` | integer | Tamanho máximo da resposta. Ignorado se for `0` |
| `stop` | string ou array | Sequências que interrompem a geração |
| `response_format` | object | Força saída em JSON. Veja a receita 5.3 em [Criando projetos com a API](/desenvolvedores/api/projetos-com-a-api) |

**Campos opcionais: ferramentas e contexto**

| Campo | Tipo | Descrição |
| - | - | - |
| `tools`, `tool_choice`, `parallel_tool_calls` | — | *Function calling* no padrão da OpenAI. Quem executa a função é o **seu** código. Veja a receita 5.5 em [Criando projetos com a API](/desenvolvedores/api/projetos-com-a-api) |
| `files` | array | Documentos e bases anexados. `[{ "type": "file", "id": "<id do arquivo>" }]` ou `[{ "type": "collection", "id": "<id da base>" }]` |
| `features` | object | `{ "web_search": true, "image_generation": true, "code_interpreter": true }`. Só funciona se a sua conta tiver a permissão correspondente |
| `variables` | object | Substituições no prompt, como `{ "{{USER_LANGUAGE}}": "pt-BR" }` |

**Campos opcionais: histórico na plataforma**

| Campo | Tipo | Descrição |
| - | - | - |
| `chat_id` | string | ID de uma conversa criada com `POST /api/v1/chats/new`. Veja abaixo |
| `id` | string | UUID que identifica a mensagem de resposta a ser gravada |

**Exemplo**

```bash theme={null}
curl -X POST https://symphony.fcamara.com/api/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "X-Enterprise-Id: SEU_ID_DE_EMPRESA" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "azure.gpt-5-chat",
    "messages": [
      { "role": "system", "content": "Responda em português, de forma objetiva." },
      { "role": "user", "content": "Resuma os riscos deste contrato." }
    ],
    "files": [{ "type": "file", "id": "3f1c..." }],
    "temperature": 0.3
  }'
```

**Resposta (`200`)**

```json theme={null}
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1764696021,
  "model": "azure.gpt-5-chat",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": { "role": "assistant", "content": "..." }
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 61, "total_tokens": 85 }
}
```

**Streaming.** Com `"stream": true`, a resposta chega como linhas `data: {...}`, cada uma com um pedaço em `choices[0].delta.content`, e termina com `data: [DONE]`. Um erro pode chegar **dentro do fluxo**, depois do `200 OK`. Veja a seção 6 de [Criando projetos com a API](/desenvolvedores/api/projetos-com-a-api).

**Histórico automático.** Se você enviar um `chat_id` e **nenhuma** mensagem com `role: "assistant"`, o Symphony recupera o histórico gravado daquela conversa e o coloca antes da sua mensagem. Assim você mantém uma conversa longa enviando só a pergunta nova. Se o seu array tiver alguma mensagem `assistant`, o Symphony entende que você controla o histórico e não injeta nada.

**Erros específicos deste endpoint**

| Status | Código | Quando |
| - | - | - |
| `400` | `INVALID_PARAMETER` | Um parâmetro está fora do que o modelo aceita |
| `400` | — | Modelo de imagem chamado sem `features.image_generation: true` |
| `402` | `CONSUMPTION_LIMIT_REACHED` / `CONSUMPTION_BLOCKED` | Seu limite de consumo acabou ou seu acesso foi bloqueado |
| `404` | `MODEL_UNAVAILABLE` | `model` fora do catálogo da empresa ou sem acesso |
| `409` | `AGENT_BASE_MODEL_UNAVAILABLE` | O agente existe, mas o modelo base dele foi removido |
| `429` | `detail.error = "quota_exceeded"` | A cota de tokens da sua empresa acabou. O corpo traz `reset_at`, com a data de renovação |
| `429` | `RATE_LIMITED` | Muitas requisições em pouco tempo, ou o fornecedor de IA limitou temporariamente |

### `POST /api/responses`

Versão compatível com a **Responses API** da OpenAI, para ferramentas que só falam esse formato. Aceita `input` (texto ou lista) no lugar de `messages` e responde em streaming no formato da Responses API.

<Note>
  **Em integrações novas, use `POST /api/chat/completions`.** Este endpoint existe só para compatibilidade.
</Note>

## 5. Arquivos

### `POST /api/v1/files/`

Envia um arquivo. O corpo é `multipart/form-data`, com o arquivo no campo `file`.

```bash theme={null}
curl -X POST https://symphony.fcamara.com/api/v1/files/ \
  -H "Authorization: Bearer sk-..." \
  -H "X-Enterprise-Id: SEU_ID_DE_EMPRESA" \
  -F "file=@contrato.pdf"
```

```json theme={null}
{
  "id": "3f1c...",
  "user_id": "b7c1...",
  "filename": "contrato.pdf",
  "data": { "status": "processing" },
  "meta": { "name": "contrato.pdf", "content_type": "application/pdf", "size": 284113 },
  "created_at": 1760533200,
  "updated_at": 1760533200
}
```

| Query | Padrão | Descrição |
| - | - | - |
| `process` | `true` | Extrai o texto do arquivo para uso no chat e nas bases. Use `false` só para guardar o arquivo sem processar |

<Warning>
  **A resposta chega antes de o arquivo estar pronto.** A leitura (extração de texto, OCR) continua em segundo plano. Antes de usar o arquivo, consulte `GET /api/v1/files/{id}` até `data.status` virar `ready`. Anexar um arquivo ainda em `processing` faz o modelo responder como se o documento estivesse vazio.
</Warning>

### `GET /api/v1/files/{id}`

Retorna os dados do arquivo, incluindo o status do processamento.

| `data.status` | Significado |
| - | - |
| `processing` | Ainda sendo lido. Consulte de novo em alguns segundos |
| `ready` | Pronto para usar no chat ou em uma base |
| `error` | Falhou. O motivo vem em `data.error` |

PDFs grandes ou digitalizados podem levar alguns minutos. Faça a consulta em intervalos (por exemplo, a cada 3 segundos) com um tempo máximo de espera.

### `GET /api/v1/files/`

Lista os seus arquivos.

| Query | Padrão | Descrição |
| - | - | - |
| `content` | `true` | Use `false` para não trazer o texto extraído e deixar a resposta mais leve |

### `GET /api/v1/files/search`

Busca arquivos pelo nome.

| Query | Obrigatório | Descrição |
| - | - | - |
| `filename` | Sim | Nome ou padrão com curinga, como `*.pdf` ou `contrato*` |
| `content` | Não | `false` para não trazer o texto extraído |

### `GET /api/v1/files/{id}/content`

Baixa o arquivo original.

| Query | Padrão | Descrição |
| - | - | - |
| `attachment` | `false` | `true` força o download (`Content-Disposition: attachment`) |

### `DELETE /api/v1/files/{id}`

Apaga o arquivo. Retorna `{ "message": "File deleted successfully" }`. Só o dono, ou quem tem permissão de escrita, pode apagar.

## 6. Bases de conhecimento

Uma base de conhecimento agrupa vários arquivos para que o modelo consulte só os trechos relevantes a cada pergunta. Para usar uma base no chat, envie `"files": [{ "type": "collection", "id": "<id da base>" }]`, ou use um agente que já tenha a base configurada.

**Fluxo completo pela API:**

<Steps>
  <Step title="Crie a base">
    `POST /api/v1/knowledge/create`
  </Step>

  <Step title="Envie cada arquivo">
    `POST /api/v1/files/` e espere o status `ready`.
  </Step>

  <Step title="Adicione os arquivos à base">
    `POST /api/v1/knowledge/{id}/file/add`
  </Step>

  <Step title="Use no chat">
    `files: [{ "type": "collection", "id": "..." }]`
  </Step>
</Steps>

### `GET /api/v1/knowledge/list/compact`

Lista as bases que você enxerga, com paginação por cursor.

| Query | Padrão | Descrição |
| - | - | - |
| `limit` | `50` | Itens por página (1 a 200) |
| `cursor` | — | `next_cursor` da página anterior |
| `search` | — | Filtra por nome ou descrição (busca parcial, sem diferenciar maiúsculas) |

```json theme={null}
{
  "items": [
    {
      "id": "kb-7a2f...",
      "name": "Políticas de RH",
      "description": "Manuais e políticas internas",
      "files_count": 12,
      "can_write": true,
      "created_at": 1760533200,
      "updated_at": 1760619600
    }
  ],
  "next_cursor": "eyJ1cGRhdGVkX2F0Ijo..."
}
```

`can_write` indica se você pode alterar a base.

### `GET /api/v1/knowledge/count`

Retorna o total de bases que você enxerga: `{ "total": 8 }`.

### `GET /api/v1/knowledge/{id}`

Retorna a base completa, com a lista de arquivos (`files`).

### `POST /api/v1/knowledge/create`

Cria uma base. **Exige a permissão `workspace.knowledge`.** Sem ela, retorna `401`.

```json theme={null}
{
  "name": "Contratos 2026",
  "description": "Contratos assinados em 2026",
  "access_control": {}
}
```

| Campo | Obrigatório | Descrição |
| - | - | - |
| `name` | Sim | Nome da base |
| `description` | Sim | Descrição (pode ser `""`) |
| `access_control` | Não | Quem mais pode ver ou editar. `{}` deixa a base **privada** (só você). Para compartilhar: `{ "read": { "group_ids": ["..."], "user_ids": ["..."] }, "write": { "group_ids": [], "user_ids": [] } }` |

Retorna a base criada, com o `id`.

### `POST /api/v1/knowledge/{id}/update`

Altera nome, descrição ou acesso. Mesmo corpo do `create`. Exige permissão de escrita na base.

### `POST /api/v1/knowledge/{id}/file/add`

Adiciona um arquivo já enviado (e com status `ready`) à base.

```json theme={null}
{ "file_id": "3f1c..." }
```

Retorna a base atualizada, com a lista de arquivos.

### `POST /api/v1/knowledge/{id}/files/batch/add`

Adiciona vários arquivos de uma vez.

```json theme={null}
[{ "file_id": "3f1c..." }, { "file_id": "8d4e..." }]
```

### `POST /api/v1/knowledge/{id}/file/remove`

Remove um arquivo da base.

```json theme={null}
{ "file_id": "3f1c..." }
```

### `DELETE /api/v1/knowledge/{id}/delete`

Apaga a base. Os arquivos continuam existindo em `/api/v1/files/`. Retorna `true`.

## 7. Conversas

Por padrão, chamadas de chat **não são gravadas**. Use estes endpoints quando quiser que as conversas do seu projeto fiquem no histórico da plataforma, onde podem ser auditadas ou continuadas pela interface.

### `POST /api/v1/chats/new`

Cria uma conversa vazia.

```json theme={null}
{
  "chat": {
    "title": "Atendimento #4821",
    "models": ["azure.gpt-5-chat"],
    "messages": []
  }
}
```

Retorna a conversa criada. Guarde o `id` e envie-o como `chat_id` em `POST /api/chat/completions`.

```json theme={null}
{
  "id": "ca49f9ae-...",
  "user_id": "b7c1...",
  "title": "Atendimento #4821",
  "chat": { ... },
  "archived": false,
  "pinned": false,
  "created_at": 1760533200,
  "updated_at": 1760533200
}
```

### `GET /api/v1/chats/list/cursor`

Lista as suas conversas, das mais recentes para as mais antigas.

| Query | Padrão | Descrição |
| - | - | - |
| `limit` | `50` | Itens por página (1 a 200) |
| `cursor` | — | `next_cursor` da página anterior |

```json theme={null}
{
  "items": [
    {
      "id": "ca49f9ae-...",
      "title": "Atendimento #4821",
      "created_at": 1760533200,
      "updated_at": 1760619600,
      "pinned": false,
      "folder_id": null,
      "tags": []
    }
  ],
  "next_cursor": null
}
```

### `GET /api/v1/chats/search`

Busca conversas pelo texto.

| Query | Obrigatório | Descrição |
| - | - | - |
| `text` | Sim | Termo buscado |
| `page` | Não | Página, começando em `1`. Cada página tem até 60 itens |

Retorna `[{ "id", "title", "created_at", "updated_at" }]`.

### `GET /api/v1/chats/{id}`

Retorna a conversa completa, com todas as mensagens em `chat.history.messages`. Só funciona para as suas conversas.

### `DELETE /api/v1/chats/{id}`

Apaga a conversa. Retorna `true`.

## 8. Fluxos (Workflows)

[Fluxos](/guia/fluxos) são sequências de etapas montadas na interface do Symphony (por exemplo: ler um documento → resumir com um agente → classificar). Pela API você **lista, executa e acompanha** os fluxos que tem permissão para usar.

**Como funciona uma execução:** a chamada de execução responde na hora com um `run_id`. O fluxo roda em segundo plano, e você consulta o resultado até ele terminar.

| `status` | Significado |
| - | - |
| `queued` | Na fila |
| `running` | Em execução |
| `completed` | Terminou com sucesso. O resultado está em `output` |
| `failed` | Falhou. O motivo está em `error`, e a etapa que falhou em `failed_node_id` |
| `cancelled` | Foi cancelado |

### `GET /api/v1/workflows/list`

Lista os fluxos que você pode usar, com paginação por cursor.

| Query | Padrão | Descrição |
| - | - | - |
| `limit` | `50` | Itens por página (1 a 200) |
| `cursor` | — | `next_cursor` da página anterior |

```json theme={null}
{
  "items": [
    {
      "id": "wf-91b3...",
      "name": "Resumo de contratos",
      "description": "Lê o contrato e gera um resumo de riscos",
      "is_active": true,
      "created_at": 1760533200,
      "updated_at": 1760619600
    }
  ],
  "next_cursor": null
}
```

### `GET /api/v1/workflows/workflow?id={id}`

Retorna o fluxo completo, incluindo as etapas (`graph`).

### `POST /api/v1/workflows/workflow/run?id={id}`

Executa o fluxo. O corpo é opcional e define a entrada da primeira etapa:

| Entrada | Formato |
| - | - |
| Texto | `{ "input": { "content": "Texto a ser processado..." } }` |
| Arquivo | `{ "input": { "file_id": "3f1c..." } }`: um arquivo enviado por `POST /api/v1/files/`, já com status `ready` |

```bash theme={null}
curl -X POST "https://symphony.fcamara.com/api/v1/workflows/workflow/run?id=wf-91b3..." \
  -H "Authorization: Bearer sk-..." \
  -H "X-Enterprise-Id: SEU_ID_DE_EMPRESA" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "file_id": "3f1c..." } }'
```

```json theme={null}
{ "run_id": "run-55c0...", "workflow_id": "wf-91b3...", "status": "queued" }
```

Retorna `429` se a sua empresa já iniciou o máximo de execuções permitido no último minuto (hoje, 30). Espere alguns segundos e tente de novo.

### `GET /api/v1/workflows/runs/detail?run_id={run_id}`

Retorna a execução, com o resultado de cada etapa. **É este endpoint que você consulta até a execução terminar.**

```json theme={null}
{
  "id": "run-55c0...",
  "workflow_id": "wf-91b3...",
  "status": "completed",
  "input": { "file_id": "3f1c..." },
  "output": { "content": "Resumo: o contrato apresenta três riscos..." },
  "error": null,
  "failed_node_id": null,
  "started_at": 1760533200,
  "ended_at": 1760533242,
  "steps": [
    {
      "node_id": "node-1",
      "node_type": "agent",
      "status": "completed",
      "output": { "content": "..." },
      "error": null
    }
  ]
}
```

### `GET /api/v1/workflows/workflow/runs?id={id}`

Lista as execuções de um fluxo, sem o detalhe das etapas.

### `POST /api/v1/workflows/runs/cancel?run_id={run_id}`

Pede o cancelamento de uma execução em andamento. Retorna `true`. Só quem iniciou a execução pode cancelá-la.

## 9. Áudio

### `POST /api/v1/audio/transcriptions`

Transcreve um áudio para texto. O corpo é `multipart/form-data`, com o áudio no campo `file`.

* **Formatos aceitos:** MP3 (`audio/mpeg`), WAV (`audio/wav`), OGG (`audio/ogg`) e M4A (`audio/x-m4a`).
* **Tamanho:** áudios acima de 25 MB são comprimidos automaticamente. Se ainda passarem do limite, retornam `FILE_TOO_LARGE`.

```bash theme={null}
curl -X POST https://symphony.fcamara.com/api/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-..." \
  -H "X-Enterprise-Id: SEU_ID_DE_EMPRESA" \
  -F "file=@reuniao.mp3"
```

```json theme={null}
{ "text": "Bom dia a todos, vamos começar...", "filename": "9a1e....mp3" }
```

### `POST /api/v1/audio/speech`

Converte texto em fala. Retorna o áudio em MP3.

```bash theme={null}
curl -X POST https://symphony.fcamara.com/api/v1/audio/speech \
  -H "Authorization: Bearer sk-..." \
  -H "X-Enterprise-Id: SEU_ID_DE_EMPRESA" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Olá, este é um teste.", "voice": "alloy" }' \
  --output fala.mp3
```

| Campo | Descrição |
| - | - |
| `input` | Texto a ser falado |
| `voice` | Uma das vozes de `GET /api/v1/audio/voices` |

O modelo de voz é definido pela configuração da sua empresa. Pedidos idênticos são servidos do cache e não contam no limite.

### `GET /api/v1/audio/voices`

Lista as vozes disponíveis: `{ "voices": [{ "id": "alloy", "name": "alloy" }] }`.

### `GET /api/v1/audio/models`

Lista os modelos de voz disponíveis: `{ "models": [...] }`.

<Note>
  **Limite:** transcrição e fala aceitam, cada uma, até 30 chamadas por minuto por empresa. Acima disso, retornam `429`.
</Note>

## 10. Status do serviço

Estes endpoints **não precisam de autenticação**.

| Endpoint | Resposta | Uso |
| - | - | - |
| `GET /health` | `{ "status": true }` | Verificar se o serviço está no ar |
| `GET /api/version` | `{ "version": "2.8.0" }` | Saber qual versão do Symphony está rodando |

## 11. O que não faz parte da API pública

Os endpoints abaixo existem, mas **não são suportados para integração**. Eles podem mudar ou ser removidos sem aviso, ou exigem um perfil que contas de integração não têm:

* **Administração da plataforma** (`/api/v1/admin/...`, gestão de usuários, empresas, grupos, modelos e consumo de terceiros): exige perfil de administrador e é feita pela interface.
* **Login por senha e SSO** (`/api/v1/auths/signin`, `/signup`, `/api/v1/auth/sso/...`): use a chave de API.
* **Rotas internas da interface**: configurações de tela, sugestões, banners, avaliações, geração automática de títulos e tags, e `GET /api/config`, que não aceita chave de API.
* **Acesso direto aos provedores de IA** (`/openai/...`, `/ollama/...`): use `POST /api/chat/completions`.
* **Geração de imagem direta** (`/api/v1/images/...`): gere imagens pelo chat, com `features.image_generation: true`.
* **Ingestão e consulta vetorial direta** (`/api/v1/retrieval/...`): use bases de conhecimento e o campo `files` do chat.
* **Gerenciamento de tarefas** (`/api/tasks/...`): para interromper uma resposta em streaming, feche a conexão.

Se o seu caso de uso precisa de algo que não está nesta página, fale com o time do Symphony. Veja [Ambientes e suporte](/desenvolvedores/api/ambientes-e-suporte).

## Documentos relacionados

* [Conectar via API](/desenvolvedores/api/conectar-api)
* [Criando projetos com a API](/desenvolvedores/api/projetos-com-a-api)
* [Erros e limites](/desenvolvedores/api/erros-e-limites)
* [Ambientes e suporte](/desenvolvedores/api/ambientes-e-suporte)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.