Pular para o conteúdo

Sua primeira chamada à API de chat da AIUBY

Equipe AIUBYEngenharia de plataforma

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

  1. 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.

  2. 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-5 e gpt-4o-mini.

  3. 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.

  4. 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.

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 no workspace da chave, ou o nome de uma rota do workspace. Não existe o formato provedor/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:

bash
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.

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 }
}
  • O texto está em choices[0].message.content.
  • usage traz 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. Com curl, acrescente -i para 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:

HTTPCódigoO que fazer
401unauthenticatedChave ausente, inválida, vencida ou revogada. Confira a variável e o cabeçalho
402insufficient_creditSaldo pré-pago zerado. Faça uma recarga em Cobrança
403forbiddenChave sem o escopo da rota. Crie uma chave com "Chamar modelos pelo Gateway"
403model_not_allowedModelo não liberado no workspace. Libere o modelo ou use outro da lista
429rate_limitedLimite de requisições por minuto. Espere e repita, com intervalo crescente
429budget_exceededOrç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.