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

# Conectar via API

> Faça a sua primeira chamada à API do Symphony em poucos minutos.

## O que é

Este início rápido leva você até a sua primeira chamada à API do **Symphony** em poucos minutos. A API permite que sistemas, scripts e automações usem os modelos, os agentes e as bases de conhecimento da sua empresa sem passar pela interface.

Depois deste início rápido, siga para:

<CardGroup cols={2}>
  <Card title="Criando projetos com a API" icon="hammer" href="/desenvolvedores/api/projetos-com-a-api">
    Guia completo, com receitas.
  </Card>

  <Card title="Referência da API" icon="book-open" href="/desenvolvedores/api/referencia-da-api">
    Todos os endpoints disponíveis, com parâmetros e respostas.
  </Card>

  <Card title="Erros e limites" icon="triangle-exclamation" href="/desenvolvedores/api/erros-e-limites">
    Como tratar falhas.
  </Card>

  <Card title="Ambientes e suporte" icon="life-ring" href="/desenvolvedores/api/ambientes-e-suporte">
    Onde testar e como pedir ajuda.
  </Card>
</CardGroup>

## Pré-requisitos

* Conta ativa no **AI Symphony**.
* Uma **chave de API** (começa com `sk-`).
* O **ID da sua empresa**, para o header `X-Enterprise-Id`.

## Passo 1 — Gerar a chave de API

<Steps>
  <Step title="Abra o AI Symphony">
    Acesse [symphony.fcamara.com](https://symphony.fcamara.com/).
  </Step>

  <Step title="Clique no seu nome de usuário">
    No canto inferior esquerdo.
  </Step>

  <Step title="Vá até Configurações" />

  <Step title="Acesse a aba Conta (ou Conexões, conforme a versão)">
    Abra **Chaves de API**.
  </Step>

  <Step title="Crie e copie a chave">
    Clique em **Chave de API** (ou "API Key") e **copie** a chave gerada. Ela começa com `sk-`.
  </Step>
</Steps>

<Tip>Cole a chave **completa**, sem espaços extras ou aspas.</Tip>

<Warning>
  **Cada usuário tem uma única chave.** Gerar uma nova substitui a anterior na hora, e toda integração que usava a chave antiga para de funcionar.
</Warning>

## Passo 2 — Descobrir o ID da sua empresa

O Symphony atende várias empresas, e cada uma tem o próprio catálogo de modelos, agentes e bases. A chave não carrega essa informação, então você informa a empresa em todas as chamadas, pelo header `X-Enterprise-Id`.

Peça esse ID ao **administrador do Symphony na sua empresa**.

<Note>
  Sem esse header, você recebe "modelo não encontrado" para um modelo que aparece funcionando na tela.
</Note>

## Passo 3 — Fazer a primeira chamada

Todas as chamadas usam os mesmos três headers:

| Header | Valor |
| - | - |
| `Authorization` | `Bearer sk-...` (sua chave) |
| `X-Enterprise-Id` | ID da sua empresa |
| `Content-Type` | `application/json` (quando há corpo JSON) |

<Info>
  **Você não precisa de cookies nem de token CSRF.** Esses passos só valem para o navegador. Quem integra com chave de API não passa por eles.
</Info>

**Endereço base:** `https://symphony.fcamara.com`

### Listar os modelos que você pode usar

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

Copie o `id` de um dos itens retornados. É esse valor que vai no campo `model`.

### Enviar uma mensagem

```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": "user", "content": "Explique o que é uma API em duas frases." }
    ]
  }'
```

Resposta (`200 OK`), no formato da OpenAI:

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

<Tip>
  **Só `model` e `messages` são obrigatórios.** Os campos `id`, `chat_id` e `session_id` são usados pela interface e só são necessários se você quiser gravar a conversa no histórico do Symphony.
</Tip>

## Exemplo em Python

A API é compatível com a da OpenAI. Com a biblioteca oficial `openai`, basta trocar a URL e a chave. Sem biblioteca, use `requests`:

<CodeGroup>
  ```python openai theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["SYMPHONY_API_KEY"],
      base_url="https://symphony.fcamara.com/api",
      default_headers={"X-Enterprise-Id": os.environ["SYMPHONY_ENTERPRISE_ID"]},
  )

  resposta = client.chat.completions.create(
      model="azure.gpt-5-chat",
      messages=[{"role": "user", "content": "Explique o que é uma API."}],
  )
  print(resposta.choices[0].message.content)
  print(f"Tokens usados: {resposta.usage.total_tokens}")
  ```

  ```python requests theme={null}
  import os
  import requests

  resposta = requests.post(
      "https://symphony.fcamara.com/api/chat/completions",
      headers={
          "Authorization": f"Bearer {os.environ['SYMPHONY_API_KEY']}",
          "X-Enterprise-Id": os.environ["SYMPHONY_ENTERPRISE_ID"],
          "Content-Type": "application/json",
      },
      json={
          "model": "azure.gpt-5-chat",
          "messages": [{"role": "user", "content": "Explique o que é uma API."}],
      },
      timeout=(10, 300),
  )

  if resposta.ok:
      print(resposta.json()["choices"][0]["message"]["content"])
  else:
      erro = resposta.json().get("error", {})
      print(resposta.status_code, erro.get("code"), erro.get("request_id"))
  ```
</CodeGroup>

## Problemas mais comuns no começo

| Sintoma | Causa provável | O que fazer |
| - | - | - |
| `401` | Chave incompleta, sem o prefixo `Bearer`, ou substituída por uma nova | Confira o header `Authorization: Bearer sk-...` |
| `403` | Chave de API desativada no ambiente, ou sem permissão | Fale com o administrador da sua empresa |
| `404` com `MODEL_UNAVAILABLE` | `X-Enterprise-Id` ausente/errado, ou `model` digitado errado | Envie o header e copie o `id` de `GET /api/models` |
| `402` | Seu limite de consumo mensal acabou | Fale com o administrador. Repetir não resolve |
| `429` | Muitas requisições em pouco tempo | Espere o tempo do header `Retry-After` e tente de novo |

A lista completa está em [Erros e limites](/desenvolvedores/api/erros-e-limites).

## Boas práticas de segurança

* Guarde a chave em **variável de ambiente** ou cofre de segredos.
* **Nunca** coloque a chave em código que roda no navegador, em repositório, em URL ou em log.
* Use sempre **HTTPS**.
* Para integrações em produção, peça ao administrador uma **conta técnica dedicada**. Assim, gerar uma nova chave pessoal não derruba a automação.

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Qual modelo devo usar no campo model?">
    Um dos `id` retornados por `GET /api/models`. Agentes criados na plataforma também aparecem nessa lista e podem ser usados da mesma forma.
  </Accordion>

  <Accordion title="Preciso do X-Enterprise-Id?">
    Sim, em todas as chamadas.
  </Accordion>

  <Accordion title="Preciso do token CSRF ou de cookies?">
    Não. Com chave de API, basta o header `Authorization`.
  </Accordion>

  <Accordion title="A chave expira?">
    Não. Ela só deixa de funcionar se você gerar outra ou se ela for revogada.
  </Accordion>
</AccordionGroup>


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