Skip to content
inferiq

Getting started

How it works

Every request takes the same path through the gateway. Knowing that path tells you what Inferiq checks, where a request can fail, and what you pay for.

Request lifecycle

  1. Your tool or code

    Sends an OpenAI-format chat request with an Inferiq key: Cline, OpenCode, Cursor, an SDK or curl.

  2. Check the key

    Gateway

    The key is hashed and looked up, revoked keys are refused, and the key’s per-minute rate limit is applied.

    fails with invalid_api_key · key_revoked · rate_limit_exceeded

  3. Validate

    Gateway

    The body is checked: a model, at least one message, well-formed tool calls. Unknown fields pass through to the model.

    fails with invalid_request

  4. Pick candidates

    Gateway

    The model must be one the key may use. An exact model is used as named; an alias expands to its models in order. Models that can’t serve the request are skipped.

    fails with unsupported_model · model_not_allowed · unsupported_parameter

  5. Check money

    Gateway

    Your balance must cover the request’s worst-case cost (prompt plus max_tokens), and the key’s daily limit must have room.

    fails with insufficient_balance · budget_exceeded

  6. Call the model

    Gateway

    Qwen3.8-27B is called, at the alias’s reasoning level. If it’s asleep it wakes up first. Rate limits, timeouts, overload and outages are retried before anything reaches you.

    fails with provider_rate_limited · provider_timeout · provider_unavailable

  7. Charge and write a receipt

    Gateway

    Actual tokens are priced, your balance is debited and the receipt written in one database transaction.

  8. Your response

    A standard chat completion or SSE stream, with the model that answered and the receipt ID in the headers.

Everything before “Call the model” happens inside Inferiq, so a request refused there costs nothing. Every error uses the same envelope. See Errors.

How a model is chosen

Every alias runs on Qwen3.8-27B. The alias decides how hard it thinks; naming the model directly, qwen/qwen3.8-27b, uses its default unless you send reasoning_effort.

AliasRuns on
inferiq/fastQwen3.8-27B, light reasoning, retried once
inferiq/balancedQwen3.8-27B, medium reasoning, retried once
inferiq/bestQwen3.8-27B, full reasoning, retried once

The model that answered comes back in the model field, the x-inferiq-model header and the receipt.

Retries and fallback

  • Rate limits, timeouts, overload (HTTP 529) and 5xx errors are retried once after a short pause.
  • A request the model rejects as invalid (HTTP 400) is not retried: it would be rejected again.
  • The model gets 5 minutes to start answering, enough to wake up after a quiet spell.
  • At most three attempts per request. Each one is listed on the receipt, and only the one that answered is charged.
  • Once tokens are streaming to you, there is no fallback: a failure ends the stream with an error event.

Send "routing": {"fallback": false} to stay on the first attempt’s model. Details are in Models & fallback.

The model

Qwen3.8-27B runs on GPUs Inferiq rents for it, behind an OpenAI-compatible server. A few things to know:

  • Requests reach it in the OpenAI chat format as you sent them, streaming and tool calls included.
  • It thinks before it answers. The thinking isn’t returned in content, but its tokens count as output.
  • It sleeps when nobody is using it and wakes up when a request arrives. That first request can take a few minutes; the ones right after it are fast.
  • Every prompt token is billed at the input price, including history your tool resends.

What gets stored

DataStoredNotes
ReceiptsAlwaysModels tried, tokens, cost, balance before and after, timing, which key. No prompt or answer text.
Prompts and answersNeverThey pass through to the model on Inferiq’s GPU servers and back. Request logging is off there.
Inferiq API keysHash onlyThe full key is shown once, when it is created.
Model server credentialsServer sideInferiq’s own keys for its GPU servers. They never leave the gateway.
LogsMetadata onlyRequest ID, models, status, cost and timing. Never bodies, keys or headers.

Architecture

The gateway is one service with a database next to it:

Coding tools · SDKs · curl
   │  HTTPS + Inferiq key (iq_…)
   ▼
Auth & rate limit ── key hash lookup
   ▼
Validation & candidates ── models the key may use · aliases
   ▼
Balance & daily limit ── worst-case cost
   ▼
Model adapter ── OpenAI-compatible
   │               timeout · retry · reasoning level
   ▼
Qwen3.8-27B on Inferiq's GPUs (wakes on demand)

Side path:  usage → receipt + ledger debit (one transaction)

Money is stored as whole micro-dollars, so balances never drift. Receipts and the ledger live in the gateway’s SQLite database (Cloudflare D1).

Fix agents

Fix agents run on top of the gateway: their model calls go through the same aliases and fallback, and their charges produce the same receipts. A fix is quoted first, the maximum is held from your balance, the patch is checked against the files you sent, and you’re charged what the run actually cost. See Fix agents.

Why it’s built this way

Limits, balances and fallback are enforced in plain gateway code before and after every model call, never by asking a model to behave.

Previous QuickstartNextConnect your tool