Guides

Chat completions

The one inference endpoint, in the OpenAI shape, request and response fields, and what the gateway does on the way through.

Endpoint

POST https://api.intelligentinference.ai/v1/chat/completions
Authorization: Bearer sk_i2_…
Content-Type: application/json

The request and response follow the OpenAI chat completions contract. Anything an OpenAI client sends is forwarded to the model; the fields below are the ones the gateway itself reads or guarantees.

Request

Field	Type	Notes
`model`	string	An i2 route id from the catalogue, verbatim. An unknown id answers `404` before the key is even checked.
`messages`	array	`{"role": "system" \| "user" \| "assistant", "content": "…"}` in order.
`stream`	boolean	`true` for server-sent events; see Streaming. Default `false`.
`max_tokens`, `temperature`, `top_p`, `stop`, …		Passed through to the model as sent.

{
  "model": "IntelligentInference/gpt-oss-120b(Global)",
  "messages": [
    {"role": "system", "content": "You are a concise assistant."},
    {"role": "user", "content": "What is a token?"}
  ],
  "max_tokens": 200,
  "temperature": 0.3
}

Response

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1787578888,
  "model": "IntelligentInference/gpt-oss-120b(Global)",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "A token is…"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 27, "completion_tokens": 64, "total_tokens": 91}
}

usage is what the request is billed on for synchronous calls. finish_reason is stop when the model finished, length when max_tokens cut it off.

What the gateway does on the way through

In order, on every request:

Resolves the route. Unknown model → 404.
Authenticates the key. Missing, wrong or revoked → 401 auth_error; past its expiry → 401 with "API Key Expired".
Checks scope. A key with allowed_models that excludes this route → 403 model_scope_error.
Checks budget. The organisation's budget and the key's own cap must both have headroom → otherwise 402, and nothing is sent upstream.
Applies the rate limit. 60 requests per minute per key → 429 beyond it.
Relays to the model server, streaming or not.
Settles. Debits the organisation's budget for the tokens used and records the request (model, key, project, status, timings, tokens, cost) in the request log.

The gateway's own overhead across those steps is about two milliseconds at the median; the measured figures are on the website.

Any request header that starts with X-I2-Meta- is recorded as metadata on that request and shows in the request log, where it is searchable. Use it to attribute traffic to your own users, features or tenants without changing the body.

X-I2-Meta-user_tag: emp-4092
X-I2-Meta-feature_tag: ticket_summary

Timeouts and disconnects

If the upstream model server fails after the key was accepted, the gateway answers a 5xx with type: "proxy_error"; nothing is billed. If your client disconnects mid-stream, the request is recorded with termination reason client_disconnect; a server-side timeout is recorded as proxy_guillotine. Both are visible in the request log so you can tell a slow model from a slow network.

Not served yet

GET /v1/models answers 404; use the catalogue.
Embedding routes appear in the catalogue but a /v1/embeddings endpoint is not documented here until it is verified end to end.

Something unclear or wrong on this page? Tell us. Machine-readable copies: llms.txt.