Quickstart

Da chave à primeira completion — e ao primeiro embedding.

1. Crie a conta e a chave

A conta e a chave nascem no console, não por API: criar organização é ato de pessoa, não de programa. Depois de entrar no console, escolha o workspace, vá em Chaves e crie uma chave de aplicação. O segredo aparece uma única vez — guarde-o na hora.

Uma chave nova já nasce com os escopos do data plane (completions.write, logs.list, mcp.invoke, entre outros) e pertence a um workspace. O que ela não pode fazer recusa com 403 escopo_insuficiente, nunca com uma resposta vazia.

2. Aponte o ambiente para o gateway

Os exemplos abaixo usam duas variáveis, para funcionarem igual na nuvem, num docker compose local ou na sua CI:

AVALON_BASE_URL — a base do gateway: https://api.avalonops.com.br.
AVALON_API_KEY — o segredo da chave que você acabou de criar.

3. Primeira completion

O mesmo corpo que você mandaria para a OpenAI. O que muda é o endereço — e tudo o que acontece ao redor da chamada.

bash

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

4. Primeiro embedding

Repare no encoding_format explícito: só "float" é aceito, e o SDK oficial manda base64 por conta própria quando você não escolhe.

bash

curl -sS "$AVALON_BASE_URL/v1/embeddings" \
  -H "Authorization: Bearer $AVALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "governança de IA",
    "encoding_format": "float"
  }'

5. A trilha da chamada que você acabou de fazer

Toda requisição do data plane vira uma linha auditável. A chave enxerga o próprio workspace, nunca outro.

bash

curl -sS "$AVALON_BASE_URL/v1/logs?limite=5" \
  -H "Authorization: Bearer $AVALON_API_KEY"

6. O mesmo, pelo SDK oficial da OpenAI

Não há SDK do AvalonOps para instalar: o SDK oficial do provedor aponta para cá pelo baseURL e continua funcionando. É o ponto do produto — governança não pode custar uma reescrita do seu código.

typescript

import OpenAI from 'openai';

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

// Completions: nada muda além do baseURL.
const resposta = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Explique governança de IA em uma frase.' }],
});

// Embeddings: 'float' é OBRIGATÓRIO aqui. Sem ele o cliente oficial manda
// base64 por conta própria, e o gateway recusa 400 encoding_nao_suportado.
const vetores = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'governança de IA',
  encoding_format: 'float',
});

O que você ganhou sem escrever código

Cada chamada virou uma linha auditável, com custo, tokens, latência e metadata.
Os portões da organização (orçamento, taxa, modelos permitidos) valem desde a primeira requisição.
Guardrails de conteúdo — inclusive máscara de PII brasileira — passam a valer quando você os configurar, sem tocar no código do cliente.
O cabeçalho x-avalon-request-id correlaciona a resposta com a linha da trilha, inclusive em streaming.