Conectar via API

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:

Criando projetos com a API

Guia completo, com receitas.

Referência da API

Todos os endpoints disponíveis, com parâmetros e respostas.

Erros e limites

Como tratar falhas.

Ambientes e suporte

Onde testar e como pedir ajuda.

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

Abra o AI Symphony

Acesse symphony.fcamara.com.

Clique no seu nome de usuário

No canto inferior esquerdo.

Vá até Configurações

Acesse a aba Conta (ou Conexões, conforme a versão)

Abra Chaves de API.

Crie e copie a chave

Clique em Chave de API (ou “API Key”) e copie a chave gerada. Ela começa com sk-.

Cole a chave completa, sem espaços extras ou aspas.

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.

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.

Sem esse header, você recebe “modelo não encontrado” para um modelo que aparece funcionando na tela.

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)

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.

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

Listar os modelos que você pode usar

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

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:

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

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.

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:

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}")

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

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.

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

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.

Preciso do X-Enterprise-Id?

Sim, em todas as chamadas.

Preciso do token CSRF ou de cookies?

Não. Com chave de API, basta o header Authorization.

A chave expira?

Não. Ela só deixa de funcionar se você gerar outra ou se ela for revogada.

Configuração do ambiente

Integrações

O que é

Criando projetos com a API

Referência da API

Erros e limites

Ambientes e suporte

Pré-requisitos

Passo 1 — Gerar a chave de API

Passo 2 — Descobrir o ID da sua empresa

Passo 3 — Fazer a primeira chamada

Listar os modelos que você pode usar

Enviar uma mensagem

Exemplo em Python

Problemas mais comuns no começo

Boas práticas de segurança

Perguntas frequentes

​O que é

Criando projetos com a API

Referência da API

Erros e limites

Ambientes e suporte

​Pré-requisitos

​Passo 1 — Gerar a chave de API

​Passo 2 — Descobrir o ID da sua empresa

​Passo 3 — Fazer a primeira chamada

​Listar os modelos que você pode usar

​Enviar uma mensagem

​Exemplo em Python

​Problemas mais comuns no começo

​Boas práticas de segurança

​Perguntas frequentes

O que é

Pré-requisitos

Passo 1 — Gerar a chave de API

Passo 2 — Descobrir o ID da sua empresa

Passo 3 — Fazer a primeira chamada

Listar os modelos que você pode usar

Enviar uma mensagem

Exemplo em Python

Problemas mais comuns no começo

Boas práticas de segurança

Perguntas frequentes