AI GridDocs
Sign Up

Chat completions

The one endpoint you will call most — OpenAI-compatible, with strict field checking.

Updated Sep 9, 2026
POST/v1/chat/completions

OpenAI-compatible. If you have an OpenAI client, point its base URL at the Grid and it works — the key already names the project, so no extra headers are required:

app.py
from openai import OpenAI

client = OpenAI(
    api_key="aig_...",
    base_url="https://api.aigridapp.com/v1",
)

resp = client.chat.completions.create(
    model="openai/gpt-oss-20b",   # get real ids from GET /v1/models
    messages=[{"role": "user", "content": "Summarise this in one line."}],
)

Request fields#

model and messages are required. Everything else is optional.

Field Type Notes
model string an id from /v1/models — a product or a chat-compatible sandbox product
messages array 1–100 messages; roles system, user, assistant, tool
stream bool see Streaming
stream_options object
max_tokens integer 0–8192, and no more than the model's own max_output_tokens
temperature number 0–2
top_p number greater than 0, at most 1
n integer must be 1 — one completion is charged per request
seed integer
stop string or array up to 4 sequences of 1–64 characters
tools array up to 64 tool definitions, under 32 KB total
tool_choice string or object under 2 KB
response_format object under 8 KB
project_id string may only restate the key's bound project

Message details: a tool message must carry the tool_call_id it answers; an assistant message may carry tool_calls and, on providers that return it, reasoning history (reasoning_content / reasoning).

Bounds. Messages plus all forwarded parameters together may not exceed 128,000 bytes, and the whole request must fit the model's published context and output limits (422 context_limit when it does not). Forwarded fields count towards the same size bound, so a large tool schema cannot settle above its reservation.

What model can name#

  • A published product assigned to your project — the common case.
  • A chat-compatible sandbox product of your project: a deployed sandbox flow whose contract is exactly one text input and one text output. The reply is a normal chat.completion whose aigrid field carries the sandbox execution id, the project and charged_micro; with stream: true the completed text arrives as one chunk. A sandbox product with any other contract answers 422 sandbox_contract — call it through /v1/sandbox/{id}/invoke instead.

Eligibility is re-checked inside the admission transaction: an id that is not callable by your project right now — a draft, a suspended deployment, a removed assignment, another project's resource — is 404 model_not_found; an eligible resource excluded by the key's own allowlist is 403 key_scope.

Idempotency#

Idempotency-Key is optional here, 8–128 characters. Repeating a key replays the saved answer without a second reservation; omitting it admits a new invocation (the server mints a unique key internally), so a retry without the header is a new, separately charged call. Every other mutation endpoint still requires the header.

Response#

Standard OpenAI shape: choices, usage, and the invocation id in the X-AIGrid-Invocation response header. Keep that id — it is the thread through usage, charges and support. See Usage and metering.

Errors#

Spend and access failures have their own codes — insufficient_budget, key_limit, key_scope, project_mismatch, model_not_found. Each names what clears it. See Errors.

A call that is refused before reaching a provider is never charged.

Next#