Chat completions

The endpoint

POST https://api.multigrid.ai/v1/chat/completions. The request body is OpenAI’s. We require exactly two things — model as a non-empty string and messages as an array with at least one entry — and pass everything else upstream untouched. temperature, top_p, stop, tools, response_format, seed, logprobs and anything a vendor shipped last week all travel through us to an OpenAI-format provider without being inspected.

Two qualifications, because “passed through” is a promise people plan against:

• Anthropic routes are built field by field, not forwarded, so a parameter the Messages API has no equivalent for cannot be honoured there. The ones that would change the answer — response_format, seed, reasoning_effort, thinking, n — are refused with a 400 naming the limitation, or routed to a non-Anthropic fallback if you have one, and never silently dropped. frequency_penalty, presence_penalty, logit_bias and parallel_tool_calls are still dropped without comment on Anthropic; that is a real gap and it is listed here rather than discovered.
• What comes back is passed through too. logprobs and usage.completion_tokens_details — including reasoning_tokens, which is most of what a reasoning model’s completion costs — are returned as the provider reported them, on both the streaming and the non-streaming path. They used to survive only on a stream, which meant the same model on the same prompt behaved differently depending on transport.

Parameters we add

Six optional top-level fields are ours, and three more are accepted for compatibility. Every one of them is removed before the request reaches a provider, so none of them can cause an upstream 400: models, provider, metadata, plugins, cache, retry, plus transforms, route and multigrid.

{
  "model": "meta/llama-3.3-70b-instruct",
  "messages": [{"role": "user", "content": "Classify this ticket."}],

  "models": ["openai/gpt-5-nano"],
  "provider": { "sort": "price", "ignore": ["together"] },
  "metadata": { "feature": "ticket-triage", "env": "prod" }
}

The model id may also carry a routing suffix — :floor, :nitro or :free — which is read off the head of the chain and stripped before anything downstream sees it. Those are documented with the rest of the provider controls.

The multigrid object

Every successful response carries one. Fields that would only repeat what you already sent are left off rather than padded in.

Streaming

Send stream: true and you get server-sent eventsStreamingThe answer arrives word by word as it is written, instead of all at once at the end. It costs the same; it just feels far faster. in OpenAI’s chunk format. Two things are ours:

• A terminal chunk before [DONE]. It carries usage and the multigrid object, because the cost is not known until the last token and so cannot be a response header. Its choices array is empty when an earlier chunk already carried a finish_reason — repeating one makes SDK accumulators emit the message twice.
• Failures after the first byte arrive in-band. The 200 is already on the wire, so an upstream error is delivered as event: error with the same envelope a non-streamed error would have had. Tokens produced before the break are still delivered, still logged and still billed.

data: {"id":"req_…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"A "},"finish_reason":null}]}

data: {"id":"req_…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"gateway"},"finish_reason":null}]}

data: {"id":"req_…","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":21,"completion_tokens":48,"total_tokens":69,"prompt_tokens_details":{"cached_tokens":0}},"multigrid":{"model":"openai/gpt-5-nano","provider":"openai","attempts":1,"cost_usd":0.0000202,"cost_micros":20,"byok":false,"request_id":"req_…"}}

data: [DONE]

Answers you are not charged for

If the model returns no text and calls no tools, the completion is waived: cost zero, waived: "zero_completion", and saved_usd showing what it would have cost. It happens for real — a content filter, a dropped completion, a context overflow reported as a clean stop — and from the outside it is indistinguishable from a model with nothing to say. A turn that only calls tools is not empty: that is the normal shape of a tool-using request and it cost real tokens to produce.

Errors

The full list, including the codes only other endpoints return, is in the error reference.