API Reference

Integrate top-tier GPUs into your application. Simple, fast, and reliable.

The API itself has no subscription: you pay for the GPU time you use, per hour, or per inference token consumed, always in Brazilian reais. Create your account, generate an API key, and get started in seconds.

Base URL

All endpoints live under the base URL below and respond in JSON:

https://gpubrazil.com

Authentication

Authenticate with an API key in the Authorization header. The key never expires and can be revoked at any time from your dashboard. Treat it like a password — anyone with the key can create and delete instances in your account.

Authorization: Bearer gpub_live_yourkeyhere

Alternatively, you can send the key in the x-api-key header.

Generate your API key in the dashboard

For security, API keys are generated and managed inside your account — in the API Keys section of the dashboard. The plaintext key is shown only once, in the authenticated area.

Open dashboard → API Keys

Endpoints

Full workflow

An instance's lifecycle is: choose the GPU → create → check status/connection → (optional) stop/start → delete. In the examples below, set your key in an environment variable:

export GPUB_API_KEY="gpub_live_yourkeyhere"

1. List GPUs and prices

Returns the catalog with the price per hour (in R$) and the gpu_key you use to create the instance. No authentication required.

curl -s "https://gpubrazil.com/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" }
  ]
}

Tip: use /api/gpus/available to also see the quantity available in real time.

2. Create an instance

Use the gpuModel = gpu_key obtained in step 1. The deploy runs in the background; the response comes back immediately with an instanceId and status creating.

curl -X POST "https://gpubrazil.com/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
  }'

Response:
{
  "success": true,
  "instance": { "instanceId": "abc123", "name": "minha-vm", "status": "creating" },
  "chargedAmount": 19.88,
  "currency": "R$",
  "message": "Instance is being created..."
}

Fields: gpuModel (required), vcpuCount (min. 2), ramGb (min. 8), storageGb (min. 40), name, and optionally sshKey and templateId (1-click template).

3. Status and SSH connection details

Query by instanceId. When the status becomes running, the connection object provides the IP, port, and a ready-to-use SSH command.

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

Response:
{
  "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. List your instances

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

5. Stop and start (optional)

Stopping halts usage-based billing while keeping the instance; starting powers it back on.

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

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

6. Delete an instance

Destroys the instance at the provider and ends billing. This is the endpoint you asked about — it exists and it's permanent.

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

Response:
{ "success": true, "message": "Instance removed" }

If the instance is still being created, the provider may refuse the deletion (HTTP 409) — try again in a few minutes.

Inference by the token (OpenAI-compatible)

Not every project needs a whole GPU running. You can also call open-weight models and pay per token consumed, using the same gpub_live_ API key and the same balance in reais that pays for the GPUs. There is no subscription, no monthly fee and no minimum token purchase: billing is proportional to the input and output tokens of each call, and the amount charged comes back inside the response itself.

The API is compatible with OpenAI's. Any SDK, framework or tool that already talks to it works here by changing only the base URL and the key:

https://gpubrasil.com.br/v1

This is the canonical API host, and it serves both languages. We do not use your prompts or your responses to train models. If your use case requires full control over the weights, the logs and the lifecycle of what you send, run the model on a dedicated GPU of your own, with no third-party API in the path.

1. List models and prices

Returns the available models, the context window size and the price per million tokens, in reais. Each model has our own id, which is what goes in the model field, and a commercial name for display only.

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

Response (excerpt):
{
  "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 } }
  ]
}

Need the price table without authenticating (for a pricing page, say)? Use GET /api/inference/models, which is public.

2. Chat completion

The format is identical to OpenAI's. The only difference is the extra usage.cost_brl field: the cost in reais of that call, already computed by the server and already deducted from your balance, so you never have to redo the math on the client.

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": "You are a concise assistant." },
      { "role": "user", "content": "Explain what a GPU is in two sentences." }
    ],
    "max_tokens": 300
  }'

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

The response's model field echoes what you asked for (here, gpub-plus), not the technical id — call it by nickname and the nickname is what comes back. cost_brl (cost of the call) and balance_brl_after (balance after it) are our additions inside the usage object; the X-Request-Id response header identifies the request on our side, so keep it if you ever need to open a ticket. Official SDKs ignore fields they do not know, so these extras break no existing integration. For plain text continuation (no chat roles), the endpoint is POST /v1/completions, with prompt instead of messages.

3. Streaming

Send "stream": true to receive the answer in chunks, as standard server-sent events. To also receive the token counts and the cost, ask for stream_options: {"include_usage": true}: usage arrives in a frame of its own, right before the final [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": "Count to three." }],
    "stream": true,
    "stream_options": { "include_usage": true }
  }'

Response (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":"One"},"finish_reason":null}]}

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

data: {"id":"chatcmpl-3a91","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":", three."},"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]

Without stream_options, the usage frame is not sent and you end up without the cost_brl for that call. Consumption is still recorded server-side and shows up in /api/inference/usage. Stop reading when you see data: [DONE], which is not JSON.

4. Official OpenAI SDK

No need to switch libraries. Point the official SDK at our base URL and use your API key; the rest of your code stays the same.

Python (pip install openai)

from openai import OpenAI

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

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

print(r.choices[0].message.content)
# cost_brl is an extra field of ours; the Python SDK exposes it in 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: 'Hello!' }],
});

console.log(r.choices[0].message.content);
console.log(r.usage.cost_brl); // cost in reais of this call

The same applies to any tool that accepts an OpenAI-compatible endpoint: fill in the base URL with https://gpubrasil.com.br/v1 and the key with your gpub_live_.

Limits, context and balance

Context window. Input and output together must fit within the context_length of the chosen model: 1,000,000 tokens on gpub-max, gpub-plus and gpub-fast, 250,000 on gpub-base and gpub-pro, and 200,000 on gpub-mini. Going over returns 400, with no charge. The live list is always at GET /v1/models.

Response size. max_tokens caps how many tokens the model may generate. Without it, the model decides where to stop within the window, and since output costs more than input on every model, setting a ceiling in production is worth it.

Balance. Before forwarding the call, the server estimates its cost. If your balance does not cover that estimate, the request is refused with 402 and nothing is spent. Top up in the dashboard and try again. Inference over the API is unlocked after your first confirmed deposit: before that the call comes back with 403 and code: "deposit_required" — to try the models without depositing, use the playground in the dashboard. Too many calls in a short window return 429; a momentary outage returns 503.

HTTP 402
{
  "error": {
    "message": "Insufficient balance to cover the estimated cost of this call.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_balance"
  }
}

Errors follow the OpenAI envelope (error.message, error.type, error.param, error.code), so existing libraries already know how to read them. Note that type and code differ: a short balance comes back as type: "insufficient_quota" with code: "insufficient_balance". Branch on the HTTP status. To track spend and volume, use GET /api/inference/usage?days=30, which returns consumption per day and per model.

Response Codes

200 · OK

Successful request

201 · Created

Instance/resource created

400 · Error

Invalid parameters or insufficient balance

401 · Unauthorized

API key missing, invalid, or revoked

403 · Forbidden

Action not allowed for this credential

402 · Insufficient balance

Balance does not cover the estimated cost of the call

429 · Rate limit

Too many requests in a short window

404 · Not Found

Instance/resource does not exist

409 · Conflict

Instance still being created — try again later

500 · Internal Error

Server error