Chat completions

Create a chat completion

Needs Call models. The request and answer have the same shape as OpenAI’s Chat Completions.

{
  "model": "openai/gpt-oss-120b",
  "messages": [
    { "role": "system", "content": "Answer in one short paragraph." },
    { "role": "user", "content": "Habari? Tell me about Zanzibar." }
  ],
  "max_tokens": 500
}

Request

modelstringRequired

A model’s name, such as openai/gpt-oss-120b. See Models.

fallbacksarray

1 to 3 other models to try, in order, when model cannot answer right now, such as ["openai/gpt-oss-20b"]. Each is checked against the request before it is sent: a fallback that does not take the tools, images, max_tokens, or other settings you sent is refused with validation_failed. A request the model refuses as invalid is not tried on the others. A stream falls back only before its first chunk. The answer’s model names the model that answered, and its AI units are that model’s.

messagesarrayRequired

The conversation, 1 to 1,000 messages. Each has a role: system, developer, user, assistant, or tool. Its content is a string, or a list of text and image_url parts. Only user messages can hold images; see Send images. An assistant message can hold tool_calls, and a tool message needs the tool_call_id it answers; see Call tools.

max_tokensinteger

The most tokens the answer may have, from 1 to the model’s most output. Without it, the model’s default output applies, not its most. max_completion_tokens is taken as the same thing.

temperaturenumber

0 to 2. Higher is more varied.

top_pnumber

0 to 1.

presence_penaltynumber

-2 to 2.

frequency_penaltynumber

-2 to 2.

stopstring or array

Up to 4 sequences that end the answer.

seedinteger

Ask for the same answer to the same request, where the model can.

ninteger

Only 1. One answer is returned.

response_formatobject

Ask for JSON: {"type": "json_object"} for any object, or {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}}} for one that matches your JSON schema, which needs "type": "object" at its top. The answer is always JSON that matches. When the model cannot give one, the call fails with answer_invalid, or with answer_cut_off when it reached max_tokens first. A call that does not stream gets a second try, and both count toward your AI units.

toolsarray

Functions the model may ask your code to run. Only for models marked for tools.

tool_choicestring or object

Whether the model must, may, or may not call a tool. Needs tools.

parallel_tool_callsboolean

Whether the model may ask for several tools at once.

promptobject

A stored prompt to put first in the conversation, as its system message: id (its name), version (to pin one; without it, the newest), and variables (a string for each {{name}} in it). See Use stored prompts.

reasoning_effortstring

How much a reasoning model thinks before it answers: low, medium (its default), or high. More thinking uses more output tokens. Only for models marked for reasoning in Models.

streamboolean

Send the answer as server-sent events as it is written. See Stream answers.

stream_options.include_usageboolean

With stream, end with a chunk that holds usage.

userstring

Your own ID for the person using your app, up to 256 characters. It is never sent to the model.

Answer

{
  "id": "chatcmpl-a1b2c3",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "openai/gpt-oss-120b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Zanzibar is an island…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1000,
    "completion_tokens": 500,
    "total_tokens": 1500,
    "units": 60
  }
}

modelstring

The model that answered, by the name you sent: model, or one of its fallbacks.

choices[0].message.contentstring

The answer. Empty when the model wants a tool instead.

choices[0].message.reasoningstring

What a reasoning model thought before it answered, kept apart from content. Left out when the model did not reason. In a stream, it arrives in delta.reasoning.

choices[0].message.tool_callsarray

The tools the model wants run, each with an id, type function, and function with its name and arguments as a JSON string. See Call tools.

choices[0].finish_reasonstring

Why it stopped: stop when it finished, length when it reached max_tokens, tool_calls when it wants a tool, content_filter when it would not answer.

usage.prompt_tokensinteger

The tokens the model read.

usage.completion_tokensinteger

The tokens the model wrote.

usage.unitsinteger

The AI units the call used. See AI units.

Headers

A call can take up to 10 minutes.