Conectar na sua máquina

Aponte a ferramenta que você já usa para o gateway.

Não há nada para instalar

O gateway já fala o protocolo da OpenAI — você só troca o endereço. Qualquer ferramenta que aceite um base URL próprio funciona: o cURL do seu terminal, os SDKs oficiais, as extensões de editor. O gateway mora em api.avalonops.com.br; os exemplos de terminal usam $AVALON_BASE_URL e $AVALON_API_KEY, como no Quickstart — e o SDK Avalon só precisa da chave: ele já sabe onde o gateway mora.

O nome do modelo segue o contrato público @slug/modelo: o slug escolhe a integração (útil quando duas servem o mesmo modelo), e o provedor recebe o nome cru.

1. cURL

Descubra os modelos e seus ids

Cada entrada já vem no contrato público @slug/modelo — o id que você copia é o que você chama.

bash

curl -sS "$AVALON_BASE_URL/v1/models" \
  -H "Authorization: Bearer $AVALON_API_KEY"

Chame pelo contrato público

O slug escolhe a integração; o provedor recebe o nome cru. Com duas integrações servindo o mesmo modelo, é assim que você escolhe o caminho.

bash

curl -sS "$AVALON_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AVALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "@openai-quickstart/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Explique governança de IA em uma frase."}]
  }'

Dados sensíveis: métricas sim, conteúdo não

O header cru x-avalon-debug: false (só o literal "false" ativa) desliga a captura de conteúdo desta requisição — o log grava normalmente tokens, custo, latência, modelo, status e o metadata (inclusive _user), e omite requisição/resposta: métricas sim, conteúdo não.

bash

curl -sS "$AVALON_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AVALON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-avalon-debug: false" \
  -d '{
    "model": "@openai-quickstart/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Explique governança de IA em uma frase."}]
  }'

Os exemplos daqui para baixo usam @openai-quickstart/gpt-4o-mini como id de exemplo — troque @openai-quickstart/gpt-4o-mini pelo id que o passo 1 acima listou para o seu provedor.

2. SDK Avalon

npm install avalonops ou pip install avalonops — o SDK próprio da Avalon: a mesma chamada do SDK da OpenAI, com metadata de primeira classe (_user identifica quem chamou nos logs), o request-id de cada resposta e o feedback por requisição.

Python

python

from avalonops import Avalon

# AVALON_API_KEY vem do ambiente; o SDK já aponta para api.avalonops.com.br
# (AVALON_BASE_URL, opcional, muda a instalação). O _user identifica quem chamou.
client = Avalon(metadata={'_user': 'seu-usuario'})

resposta = client.chat.completions.create(
    model='@openai-quickstart/gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Explique governança de IA em uma frase.'}],
)

NodeJS

typescript

import Avalon from 'avalonops';

// AVALON_API_KEY vem do ambiente; o SDK já aponta para api.avalonops.com.br
// (AVALON_BASE_URL, opcional, muda a instalação). O _user identifica quem chamou.
const client = new Avalon({ metadata: { _user: 'seu-usuario' } });

const resposta = await client.chat.completions.create({
  model: '@openai-quickstart/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Explique governança de IA em uma frase.' }],
});

3. Dados sensíveis: métricas sim, conteúdo não

debug: false no construtor (debug=False em Python) manda x-avalon-debug: false em toda chamada deste cliente — o log continua gravando tokens, custo, latência, modelo, status e o metadata (inclusive _user), e passa a omitir requisição e resposta: métricas sim, conteúdo não. O mesmo efeito, por requisição, é o header cru x-avalon-debug: false visto no passo 1 acima.

Python

python

from avalonops import Avalon

# debug=False (a partir do avalonops 0.2.0) desliga a captura de
# conteúdo do log desta instalação do cliente — métricas sim, conteúdo não.
client = Avalon(debug=False)

resposta = client.chat.completions.create(
    model='@openai-quickstart/gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Explique governança de IA em uma frase.'}],
)

NodeJS

typescript

import Avalon from 'avalonops';

// debug: false (a partir do avalonops 0.2.0) desliga a captura de
// conteúdo do log desta instalação do cliente — métricas sim, conteúdo não.
const client = new Avalon({ debug: false });

const resposta = await client.chat.completions.create({
  model: '@openai-quickstart/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Explique governança de IA em uma frase.' }],
});

4. SDK oficial da OpenAI

Python

Só o base_url muda.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ['AVALON_API_KEY'],
    base_url=os.environ['AVALON_BASE_URL'] + '/v1',
)
resposta = client.chat.completions.create(
    model='@openai-quickstart/gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Explique governança de IA em uma frase.'}],
)

NodeJS

Só o baseURL muda.

typescript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.AVALON_API_KEY,
  baseURL: process.env.AVALON_BASE_URL + '/v1',
});

const resposta = await client.chat.completions.create({
  model: '@openai-quickstart/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Explique governança de IA em uma frase.' }],
});

5. VSCode

Continue (config.yaml)

Salve em ~/.continue/config.yaml — o config.json está obsoleto no Continue. A chave vem de um secret (nunca colada no arquivo); o apiBase já aponta para o gateway do SaaS.

yaml

name: AvalonOps
version: 0.0.1
schema: v1
models:
  - name: AvalonOps · gpt-4o-mini
    provider: openai
    model: "@openai-quickstart/gpt-4o-mini"
    apiBase: "https://api.avalonops.com.br/v1"
    apiKey: ${{ secrets.AVALON_API_KEY }}

Cline e Roo Code

Escolha o provedor OpenAI Compatible e preencha:

Base URL — https://api.avalonops.com.br/v1
API Key — $AVALON_API_KEY
Model ID — @openai-quickstart/gpt-4o-mini

O GitHub Copilot não aceita endpoint próprio — para ele, este tutorial não se aplica.