Referência de API

Integre GPUs de topo de linha à sua aplicação. Simples, rápido e confiável.

A API em si não tem mensalidade: você paga pelo tempo de GPU por hora ou por token de inferência consumido, sempre em reais. Crie sua conta, gere uma API key e comece em segundos.

URL base

Todos os endpoints ficam sob a URL base abaixo e respondem em JSON:

https://gpubrasil.com.br

Autenticação

Autentique com uma API key no header Authorization. A key não expira e pode ser revogada a qualquer momento no painel. Trate-a como uma senha — quem tiver a key pode criar e apagar instâncias na sua conta.

Authorization: Bearer gpub_live_suachaveaqui

Alternativamente, você pode enviar a key no header x-api-key.

Gere sua API key no painel

Por segurança, as API keys são geradas e gerenciadas dentro da sua conta — na seção API Keys do painel. A chave em claro é exibida uma única vez, no ambiente autenticado.

Abrir painel → API Keys

Endpoints

Fluxo completo

O ciclo de vida de uma instância é: escolher a GPU → criar → consultar status/conexão → (opcional) parar/iniciar → deletar. Nos exemplos abaixo, defina sua chave em uma variável de ambiente:

export GPUB_API_KEY="gpub_live_suachaveaqui"

1. Listar GPUs e preços

Retorna o catálogo com preço por hora (em R$) e o gpu_key que você usa para criar a instância. Não exige autenticação.

curl -s "https://gpubrasil.com.br/api/gpus"

Resposta (resumo):
{
  "gpus": [
    { "model": "NVIDIA H100 PCIe 80GB", "gpu_key": "premium_H100-80G-PCIe",
      "pricePerHourBrl": 19.88, "provider": "premium" },
    { "model": "RTX 4090", "gpu_key": "economic_RTX_4090",
      "pricePerHourBrl": 3.34, "provider": "economic" }
  ]
}

Dica: use /api/gpus/available para ver também a quantidade disponível em tempo real.

2. Criar instância

Use o gpuModel = gpu_key obtido no passo 1. O deploy roda em segundo plano; a resposta volta na hora com um instanceId e status creating.

curl -X POST "https://gpubrasil.com.br/api/instances/deploy" \
  -H "Authorization: Bearer $GPUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "minha-vm",
    "gpuModel": "premium_H100-80G-PCIe",
    "vcpuCount": 8,
    "ramGb": 64,
    "storageGb": 100
  }'

Resposta:
{
  "success": true,
  "instance": { "instanceId": "abc123", "name": "minha-vm", "status": "creating" },
  "chargedAmount": 19.88,
  "currency": "R$",
  "message": "Instância sendo criada..."
}

Campos: gpuModel (obrigatório), vcpuCount (mín. 2), ramGb (mín. 8), storageGb (mín. 40), name, e opcionalmente sshKey e templateId (template 1-clique).

3. Status e dados de conexão SSH

Consulte pelo instanceId. Quando o status virar running, o objeto connection traz IP, porta e o comando SSH pronto.

curl -s "https://gpubrasil.com.br/api/instances/abc123" \
  -H "Authorization: Bearer $GPUB_API_KEY"

Resposta:
{
  "id": "abc123",
  "name": "minha-vm",
  "status": "running",
  "gpu_model": "premium_H100-80G-PCIe",
  "connection": {
    "ip": "203.0.113.42",
    "port": 22,
    "user": "ubuntu",
    "sshCommand": "ssh -i ~/.ssh/your_key -p 22 ubuntu@203.0.113.42"
  },
  "resources": { "vcpuCount": 8, "ramGb": 64, "storageGb": 100 },
  "pricing": { "hourlyRateBrl": 19.88 }
}

4. Listar suas instâncias

curl -s "https://gpubrasil.com.br/api/instances" \
  -H "Authorization: Bearer $GPUB_API_KEY"

5. Parar e iniciar (opcional)

Pausar interrompe a cobrança por uso mantendo a instância; iniciar volta a ligá-la.

curl -X POST "https://gpubrasil.com.br/api/instances/abc123/stop" \
  -H "Authorization: Bearer $GPUB_API_KEY"

curl -X POST "https://gpubrasil.com.br/api/instances/abc123/start" \
  -H "Authorization: Bearer $GPUB_API_KEY"

6. Deletar instância

Destrói a instância no provedor e encerra a cobrança. É o endpoint que você perguntou — ele existe e é definitivo.

curl -X DELETE "https://gpubrasil.com.br/api/instances/abc123" \
  -H "Authorization: Bearer $GPUB_API_KEY"

Resposta:
{ "success": true, "message": "Instância removida" }

Se a instância ainda estiver sendo criada, o provedor pode recusar a deleção (HTTP 409) — tente de novo em alguns minutos.

Inferência por token (compatível com OpenAI)

Nem todo projeto precisa de uma GPU inteira ligada. Você também pode chamar modelos de pesos abertos pagando por token consumido, usando a mesma API key gpub_live_ e o mesmo saldo em reais que paga as GPUs. Não existe assinatura, não existe mensalidade e não existe mínimo de compra de tokens: a cobrança é proporcional aos tokens de entrada e de saída de cada chamada, e o valor debitado volta na própria resposta.

A API é compatível com a da OpenAI. Qualquer SDK, framework ou ferramenta que já converse com ela funciona aqui trocando apenas a URL base e a chave:

https://gpubrasil.com.br/v1

Não usamos seus prompts nem suas respostas para treinar modelos. Se o seu caso exige controle total sobre os pesos, os logs e o ciclo de vida do que trafega, rode o modelo em uma GPU dedicada só sua, sem API de terceiro no caminho.

1. Listar modelos e preços

Devolve os modelos disponíveis, o tamanho da janela de contexto e o preço por milhão de tokens, em reais. Cada modelo tem um id nosso, que é o que vai no campo model, e um name comercial só para exibição.

curl -s "https://gpubrasil.com.br/v1/models" \
  -H "Authorization: Bearer $GPUB_API_KEY"

Resposta (resumo):
{
  "object": "list",
  "data": [
    { "id": "gpub-fast", "object": "model", "owned_by": "gpubrasil",
      "name": "DeepSeek V4 Flash", "context_length": 1000000,
      "pricing": { "currency": "BRL", "inputPerMillion": 0.49, "outputPerMillion": 1.09 } },
    { "id": "gpub-mini", "object": "model", "owned_by": "gpubrasil",
      "name": "Qwen 3.6 35B", "context_length": 200000,
      "pricing": { "currency": "BRL", "inputPerMillion": 0.59, "outputPerMillion": 3.49 } },
    { "id": "gpub-plus", "object": "model", "owned_by": "gpubrasil",
      "name": "Qwen 3.8 27B", "context_length": 1000000,
      "pricing": { "currency": "BRL", "inputPerMillion": 0.69, "outputPerMillion": 3.99 } },
    { "id": "gpub-pro", "object": "model", "owned_by": "gpubrasil",
      "name": "GLM 5.3 Flash", "context_length": 250000,
      "pricing": { "currency": "BRL", "inputPerMillion": 1.89, "outputPerMillion": 5.90 } },
    { "id": "gpub-base", "object": "model", "owned_by": "gpubrasil",
      "name": "GLM 5.2", "context_length": 250000,
      "pricing": { "currency": "BRL", "inputPerMillion": 7.90, "outputPerMillion": 17.90 } },
    { "id": "gpub-max", "object": "model", "owned_by": "gpubrasil",
      "name": "Kimi K3", "context_length": 1000000,
      "pricing": { "currency": "BRL", "inputPerMillion": 17.90, "outputPerMillion": 84.90 } }
  ]
}

Precisa da tabela de preços sem autenticar (para uma página de preços, por exemplo)? Use GET /api/inference/models, que é público.

2. Chat completion

Formato idêntico ao da OpenAI. A única diferença é o campo extra usage.cost_brl: o custo em reais daquela chamada, já calculado pelo servidor e já debitado do seu saldo, para você não precisar refazer a conta no cliente.

curl -X POST "https://gpubrasil.com.br/v1/chat/completions" \
  -H "Authorization: Bearer $GPUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpub-plus",
    "messages": [
      { "role": "system", "content": "Você responde em português do Brasil." },
      { "role": "user", "content": "Explique o que é uma GPU em duas frases." }
    ],
    "max_tokens": 300
  }'

Resposta:
{
  "id": "chatcmpl-8f2c1b",
  "object": "chat.completion",
  "created": 1754870400,
  "model": "gpub-plus",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Uma GPU é um processador..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 500,
    "completion_tokens": 300,
    "total_tokens": 800,
    "cost_brl": 0.0085,
    "balance_brl_after": 92.15
  }
}

O campo model da resposta devolve o que você pediu (aqui, gpub-plus), não o identificador técnico — se você chamar por apelido, é o apelido que volta. cost_brl (custo da chamada) e balance_brl_after (saldo depois dela) são acréscimos nossos dentro do objeto usage; o cabeçalho X-Request-Id identifica a requisição no nosso lado, guarde-o se precisar abrir um chamado. SDKs oficiais ignoram campos que não conhecem, então esses extras não quebram nenhuma integração existente. Para continuação de texto puro (sem papéis de conversa), o endpoint é POST /v1/completions, com prompt no lugar de messages.

3. Streaming

Mande "stream": true para receber a resposta em pedaços, no padrão server-sent events. Para receber também o consumo e o custo, peça stream_options: {"include_usage": true}: o usage chega em um frame próprio, logo antes do [DONE].

curl -N -X POST "https://gpubrasil.com.br/v1/chat/completions" \
  -H "Authorization: Bearer $GPUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpub-fast",
    "messages": [{ "role": "user", "content": "Conte até três." }],
    "stream": true,
    "stream_options": { "include_usage": true }
  }'

Resposta (text/event-stream):
data: {"id":"chatcmpl-3a91","object":"chat.completion.chunk","model":"gpub-fast","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-3a91","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Um"},"finish_reason":null}]}

data: {"id":"chatcmpl-3a91","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":", dois"},"finish_reason":null}]}

data: {"id":"chatcmpl-3a91","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":", três."},"finish_reason":null}]}

data: {"id":"chatcmpl-3a91","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-3a91","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":9,"total_tokens":23,"cost_brl":0.0000155,"balance_brl_after":92.15}}

data: [DONE]

Sem stream_options, o frame de usage não é enviado e você fica sem o cost_brl daquela chamada. O consumo continua registrado no servidor e aparece em /api/inference/usage. Encerre a leitura ao ver data: [DONE], que não é JSON.

4. SDK oficial da OpenAI

Não é preciso trocar de biblioteca. Aponte o SDK oficial para a nossa URL base e use a sua API key; o resto do código continua igual.

Python (pip install openai)

from openai import OpenAI

client = OpenAI(
    base_url="https://gpubrasil.com.br/v1",
    api_key="gpub_live_suachaveaqui",
)

r = client.chat.completions.create(
    model="gpub-mini",
    messages=[{"role": "user", "content": "Olá!"}],
)

print(r.choices[0].message.content)
# cost_brl é um campo extra nosso; no SDK Python ele chega em model_extra
print(r.usage.model_extra["cost_brl"])

Node.js (npm i openai)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://gpubrasil.com.br/v1',
  apiKey: process.env.GPUB_API_KEY,
});

const r = await client.chat.completions.create({
  model: 'gpub-mini',
  messages: [{ role: 'user', content: 'Olá!' }],
});

console.log(r.choices[0].message.content);
console.log(r.usage.cost_brl); // custo em reais desta chamada

Vale o mesmo para ferramentas que aceitam um endpoint compatível com a OpenAI: preencha a URL base com https://gpubrasil.com.br/v1 e a chave com a sua gpub_live_.

Limites, contexto e saldo

Janela de contexto. Entrada e saída somadas precisam caber no context_length do modelo escolhido: 1.000.000 tokens em gpub-max, gpub-plus e gpub-fast, 250.000 em gpub-base e gpub-pro, e 200.000 em gpub-mini. Passar disso devolve 400, sem cobrança. A lista viva está sempre em GET /v1/models.

Tamanho da resposta. max_tokens limita quantos tokens o modelo pode gerar. Sem ele, o modelo decide onde parar dentro da janela, e como a saída custa mais que a entrada em todos os modelos, vale definir um teto em produção.

Saldo. Antes de encaminhar a chamada, o servidor estima o custo. Se o seu saldo não cobrir essa estimativa, a requisição é recusada com 402 e nada é gasto. Recarregue por Pix no painel e tente de novo. A inferência pela API é liberada depois do primeiro depósito confirmado: antes disso a chamada volta com 403 e code: "deposit_required" — para experimentar sem depositar, use o playground do painel. Um excesso de chamadas em pouco tempo devolve 429; uma indisponibilidade momentânea devolve 503.

HTTP 402
{
  "error": {
    "message": "Saldo insuficiente para cobrir o custo estimado desta chamada.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_balance"
  }
}

Os erros seguem o envelope da OpenAI (error.message, error.type, error.param, error.code), então bibliotecas existentes já sabem lê-los. Repare que type e code não são iguais: saldo curto vem como type: "insufficient_quota" e code: "insufficient_balance". Trate a decisão pelo status HTTP. Para acompanhar gasto e volume, use GET /api/inference/usage?days=30, que devolve o consumo por dia e por modelo.

Códigos de Resposta

200 · OK

Requisição bem-sucedida

201 · Criado

Instância/recurso criado

400 · Erro

Parâmetros inválidos ou saldo insuficiente

401 · Não autorizado

API key ausente, inválida ou revogada

403 · Proibido

Ação não permitida para esta credencial

402 · Saldo insuficiente

O saldo não cobre o custo estimado da chamada

429 · Limite de requisições

Muitas requisições em pouco tempo

404 · Não encontrado

Instância/recurso inexistente

409 · Conflito

Instância ainda sendo criada — tente depois

500 · Erro interno

Erro no servidor