Quickstart da API de Chat

Use o chat fundamentado na Biblioteca do Vulgate através da interface Chat Completions compatível com OpenAI.

21 de mai. de 2026

A API de Chat é compatível com OpenAI. Ela implementa o mesmo formato /chat/completions da API OpenAI Chat Completions, então qualquer cliente que fale esse protocolo — os SDKs oficiais openai, o SDK ai da Vercel, suas próprias chamadas fetch — funciona apontando para o Vulgate.

Internamente, o Vulgate executa recuperação nas Bibliotecas às quais sua chave de API tem acesso e alimenta as passagens relevantes para o modelo. As respostas incluem citações referenciando as passagens fonte.

A referência completa está em /developers/chat/overview. Este é o mínimo para começar.

Uma requisição mínima

curl -X POST "https://vulgate.ai/api/chat/completions" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vulgate-1",
    "messages": [
      {"role": "user", "content": "Resuma os ensinamentos do concílio sobre adoração eucarística."}
    ]
  }'

Resposta (truncada):

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "vulgate-1",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Os concílios ensinam que a adoração eucarística..."
    },
    "finish_reason": "stop"
  }],
  "citations": [
    {
      "cited_text": "<p>...</p>",
      "document_title": "Ecclesia de Eucharistia",
      "document_index": 0,
      "document_author": "João Paulo II",
      "source_url": null
    }
  ]
}

Streaming

Defina stream: true e você receberá eventos server-sent no formato chat.completion.chunk do OpenAI:

curl -X POST "https://vulgate.ai/api/chat/completions" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vulgate-1",
    "stream": true,
    "messages": [{"role": "user", "content": "Olá"}]
  }'

Cada chunk é um objeto JSON prefixado com data: , terminando com data: [DONE]. Idêntico ao OpenAI; parsers existentes funcionam.

Bibliotecas

Diferentemente da API de Busca, a API de Chat não aceita um parâmetro libraries. A IA automaticamente pesquisa nas Bibliotecas às quais a equipe da sua chave de API tem acesso.

Usando o SDK Python do OpenAI

O SDK OpenAI funciona diretamente — apenas aponte base_url para o Vulgate:

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["VULGATE_API_KEY"],
    base_url="https://vulgate.ai/api",
)

response = client.chat.completions.create(
    model="vulgate-1",
    messages=[{"role": "user", "content": "Resuma o cânone sobre confirmação."}],
)
print(response.choices[0].message.content)

Modelos

Passe vulgate-1 (ou o apelido vulgate) no campo model. Veja /developers/chat/overview para a lista atual.

Limites de taxa e timeouts

  • 10 requisições por 10 segundos por equipe (janela deslizante).
  • 120 segundos por requisição.

Exceder o limite de taxa retorna 429 com cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

Erros

A API usa códigos de status HTTP padrão:

  • 401 — chave de API inválida ou ausente.
  • 429 — limite de taxa excedido.
  • 400 — corpo da requisição malformado; o corpo da resposta explica o que está errado.
  • 500 / 502 — problema do lado do Vulgate; tente novamente com backoff exponencial.

Relacionados

Pesquisar ajuda