Sua primeira chamada à API de chat da AIUBY
AIUBY Models + AI Gateway + curl
Este tutorial leva de uma conta nova até a primeira resposta de um modelo pela API da AIUBY, usando só curl. A rota de chat segue o formato da API de chat da OpenAI, então o que você aprender aqui serve também para o SDK oficial, trocando o endereço base. No caminho, mostramos os erros que aparecem quando falta algum passo e o que fazer em cada um.
#Antes de começar
- Um terminal com
curl. - Um e-mail de trabalho, ou uma conta Google ou GitHub, para criar a conta.
- Um aplicativo de banco para pagar um Pix: o consumo de IA é pré-pago.
Você precisa ser o dono da organização para adicionar o produto e recarregar. Quem cria a conta do zero já é.
#Preparar a conta
Crie a conta
Em aiuby.com/plataforma/cadastro, entre com Google, GitHub ou com o e-mail de trabalho. Pelo e-mail, você recebe um link de confirmação e define a senha.
Adicione o Models
Uma conta nova abre no catálogo de produtos. Adicione o Models. Adicionar não tem custo: a plataforma cria a conta de consumo pré-paga, com saldo zero, e libera uma lista inicial de modelos, que inclui
claude-sonnet-5-5egpt-4o-mini.Recarregue o saldo
Na tela Cobrança, escolha um valor de R$ 20 a R$ 50.000 e gere o Pix. Ele vale por 30 minutos. A tela confirma sozinha quando o pagamento cai, e o valor entra no saldo.
Crie a chave de API
Em Acesso → Chaves de API, crie uma chave para um workspace com o escopo "Chamar modelos pelo Gateway". O token aparece uma única vez: copie e guarde num cofre de segredos.
bash export AIUBY_TOKEN="aiuby_..."
Nota
Uma chave vale para um único workspace e só faz o que os escopos dela permitem. Para este tutorial, um escopo basta. A validade padrão é de 90 dias, e a revogação é imediata, pela mesma tela.
#A chamada
O endereço base é https://aiuby.com, e a rota de chat é POST /api/gateway/v1/chat/completions. O token vai no cabeçalho de autorização.
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?"}
]
}'modelemessagessão obrigatórios.modelé o identificador de um modelo liberado no workspace da chave, ou o nome de uma rota do workspace. Não existe o formatoprovedor/modelo.- Um campo fora da lista aceita responde
400 invalid_request, em vez de ser ignorado. Vale conferir a grafia. - O corpo tem até 4 MB.
Para saber quais identificadores a sua chave pode usar, liste os modelos do workspace:
curl -sS "https://aiuby.com/api/gateway/v1/models" -H "Authorization: Bearer $AIUBY_TOKEN"O id de cada item da lista é o valor a usar no campo model.
#Como ler a 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.
{
"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 }
}- O texto está em
choices[0].message.content. usagetraz os tokens de entrada e de saída da chamada. É sobre eles que o custo é calculado.- Toda resposta do Gateway traz o cabeçalho
x-aiuby-request-id. Guarde esse valor nos seus logs: é com ele que a equipe localiza uma chamada. Comcurl, acrescente-ipara ver os cabeçalhos.
#Os erros mais comuns
O Gateway responde erros sempre com um objeto error, que traz code, message e request_id. Numa primeira integração, estes são os que mais aparecem:
| HTTP | Código | O que fazer |
|---|---|---|
| 401 | unauthenticated | Chave ausente, inválida, vencida ou revogada. Confira a variável e o cabeçalho |
| 402 | insufficient_credit | Saldo pré-pago zerado. Faça uma recarga em Cobrança |
| 403 | forbidden | Chave sem o escopo da rota. Crie uma chave com "Chamar modelos pelo Gateway" |
| 403 | model_not_allowed | Modelo não liberado no workspace. Libere o modelo ou use outro da lista |
| 429 | rate_limited | Limite de requisições por minuto. Espere e repita, com intervalo crescente |
| 429 | budget_exceeded | Orçamento do workspace esgotado. Quem administra precisa rever o valor |
A diferença que importa no código: rate_limited e concurrency_limited valem uma nova tentativa. insufficient_credit, budget_exceeded e model_not_allowed não: repetir não resolve, alguém precisa agir na área do cliente. Por padrão, um workspace aceita 60 requisições por minuto e 20 chamadas simultâneas.
Atenção
Falha do provedor do modelo chega como 502, 503 ou 504. Um erro de autenticação do provedor também vira 502, não 401: a sua chave da AIUBY continua válida.
#Ver o consumo
- Cada chamada desconta do saldo o valor em reais. O saldo e as últimas recargas ficam na tela Cobrança.
- Em Configurações → Orçamento, dono e administrador veem o gasto do mês ao lado do teto da organização e de cada workspace.
- O gasto por pessoa, chave, modelo e projeto fica em Uso e custos, para quem tem o Guard.
- Para separar o custo por projeto, envie o cabeçalho opcional
x-aiuby-project, com até 63 caracteres: letras minúsculas, números, ponto, hífen e sublinhado.
Os provedores cobram em dólar. O valor em reais de uma chamada é o custo dela no provedor multiplicado pelo preço em reais por dólar de custo da organização, arredondado para cima, e esse preço acompanha o câmbio. A conta completa está em Cobrança.
#O que ainda não existe
Limite
Não há rota pública de embeddings por chave de API, nem recarga por chave de API ou recarga automática: a recarga é sempre um Pix gerado pelo dono na tela.
- O pay-per-use, com fatura no cartão de crédito, ainda não está disponível. Hoje a única modalidade é o pré-pago.
- Os modelos rodam nos servidores dos provedores, fora do Brasil.
- Uma organização que entra pelo catálogo tem um teto de segurança de consumo de IA de US$ 100 por mês. O dono ajusta abaixo disso em Orçamento e modelos liberados.
Daqui, os próximos passos naturais são o streaming e os campos aceitos, em Chat, e a lista completa de códigos, em Erros.



