This page is not yet available in English. Read it in Portuguese

Skip to content
Menu da documentação

API

Chat

A rota de chat compatível com a OpenAI: corpo, streaming, o cabeçalho de projeto e o que muda ao chamar modelos de outros provedores.

#Requisição

bash
curl -sS -X POST "https://aiuby.com/api/gateway/v1/chat/completions" \
  -H "Authorization: Bearer $AIUBY_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 512,
    "messages": [
      {"role": "system", "content": "Responda em português, em até três frases."},
      {"role": "user", "content": "O que é uma trilha de auditoria?"}
    ]
  }'
  • model e messages são obrigatórios.
  • model é o identificador de um modelo liberado ou o nome de uma rota do workspace. Veja Models.
  • O corpo tem até 4 MB.

#Resposta

A resposta segue o formato de chat da OpenAI, inclusive quando o modelo é de outro provedor: o Gateway traduz a ida e a volta.

json
{
  "id": "...",
  "object": "chat.completion",
  "model": "claude-sonnet-5-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Uma trilha de auditoria é ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 31, "completion_tokens": 48, "total_tokens": 79 }
}

#Streaming

Com "stream": true, a resposta chega em eventos do servidor (SSE), no formato da OpenAI. A política de dados sensíveis vale também para o texto que vai chegando.

typescript
const stream = await client.chat.completions.create({
  model: 'claude-sonnet-5-5',
  messages: [{ role: 'user', content: 'Oi' }],
  stream: true,
})
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? '')

Falha no meio da resposta

Quando a resposta começa, o status 200 já foi enviado. Se o provedor cair depois disso, não chega um JSON de erro: a conexão é encerrada e a leitura do stream falha no seu código.

  • O que já tinha saído foi entregue. O texto chega com um atraso de poucos caracteres, porque o fim de cada pedaço fica retido para conferir dado sensível partido entre pedaços.
  • A chamada fica registrada como erro do provedor, e o que foi gerado até a queda conta como uso, estimado pelo tamanho. Esse parcial é cobrado.
  • Não há troca para o modelo alternativo no meio da resposta: a alternativa só entra antes do primeiro pedaço.
  • Sem nenhum pedaço por 60 segundos, o Gateway encerra por inatividade. Um stream dura no máximo 15 minutos.
  • Se o seu cliente fechar a conexão, o Gateway encerra a chamada no provedor e registra o parcial do mesmo jeito.

Para tratar: guarde o cabeçalho x-aiuby-request-id assim que a resposta abrir, trate a falha de leitura como resposta incompleta e, se for repetir, repita a chamada inteira.

#Separar o custo por projeto

O cabeçalho opcional x-aiuby-project marca a chamada com um projeto, para orçamento e relatório. Aceita até 63 caracteres: letras minúsculas, números, ponto, hífen e sublinhado. Um valor inválido responde 400.

typescript
const client = new OpenAI({
  apiKey: process.env.AIUBY_TOKEN,
  baseURL: 'https://aiuby.com/api/gateway/v1',
  defaultHeaders: { 'x-aiuby-project': 'atendimento-web' },
})

#Rotas nativas

Para usar o formato próprio de um provedor, há duas rotas que só aceitam modelos dele:

bash
curl -sS -X POST "https://aiuby.com/api/gateway/anthropic/v1/messages" \
  -H "Authorization: Bearer $AIUBY_TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":256,"messages":[{"role":"user","content":"Olá"}]}'
  • Na rota da Anthropic, o cabeçalho anthropic-version é opcional; sem ele vale 2023-06-01.
  • A rota nativa da OpenAI é POST /api/gateway/openai/v1/chat/completions.

#Campos aceitos

  • Um campo fora da lista aceita responde 400 invalid_request, em vez de ser ignorado.
  • max_tokens vai até 200.000.
  • Ferramentas: só do tipo function no formato da OpenAI, ou custom no formato da Anthropic.

Limite

Não há rota pública de embeddings por chave de API.