API docs

Quickstart

1. Create a key. Sign up, open API keys and create one. The full key is shown once, so copy it then.
2. Top up. Add from $5 in Billing. Requests without balance answer 402.
3. Change the base URL. Point your SDK at https://refillhub.biz.id/api/v1. The marked line is the only change.

import OpenAI from "openai"; const client = new OpenAI({  baseURL: "https://refillhub.biz.id/api/v1",  apiKey: process.env.REFILLHUB_API_KEY,}); const reply = await client.chat.completions.create({  model: "gemini-3.1-flash-lite",  messages: [{ role: "user", content: "Explain token metering." }],}); console.log(reply.choices[0].message.content);

Authentication

Send the key on every request as Authorization: Bearer rh_…. Keys start with rh_. A missing header answers missing_api_key; a revoked or unknown key answers invalid_api_key. Keep keys on the server, never in browser code.

Endpoints

POST /api/v1/chat/completions

The OpenAI chat completions request. Model ids carry the provider prefix, for example gemini-3.1-flash-lite. Every response has an x-request-id header; non-streaming responses also carry x-refillhub-cost-usd, the amount charged.

GET /api/v1/models

Public, no key needed. Lists every enabled model with its context length and price per million input and output tokens, in the OpenAI list shape. The same data prints the models and prices page.

curl https://refillhub.biz.id/api/v1/models

Streaming

Set stream: true for server-sent events. Deltas are forwarded as they arrive and usage is requested on the final chunk, so a streamed request is billed the same way as one that waits.

const stream = await client.chat.completions.create({  model: "gemini-3.1-flash-lite",  messages: [{ role: "user", content: "Write a haiku about refuelling." }],  stream: true,}); for await (const chunk of stream) {  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");}

Errors

A failure returns { "error": { "message", "type", "code" } } with a matching HTTP status. Branch on code; show message to people.

HTTP/1.1 402 Payment Required {  "error": {    "message": "Your balance is too low for this request. Top up in the dashboard.",    "type": "insufficient_quota",    "code": "insufficient_balance"  }}

When your balance covers the prompt but not the full output you asked for, max_tokens is lowered to what the balance can pay for instead of failing the call.

Limits and spend caps

Each key allows 600 requests a minute unless you set its own limit. A 429 rate_limited carries retry-after in seconds, plus x-ratelimit-limit-requests and x-ratelimit-remaining-requests. Request bodies are capped at 4 MB.

A key can carry a spend limit. Once it is spent the key answers key_spend_limit until you raise it. Usage in the dashboard lists every request with its model, tokens, cost and latency; prompt and completion text are not stored.