Create Chat Completion

modelrequiredstring

The model ID to use. Recommended: "deepbrain-router" (auto-routes to the best model). See Models for available identifiers. Other options: "gpt-5", "gpt-5.4", "gpt-5-nano".

messagesrequiredChatCompletionMessageParam[]

The conversation history as an array of message objects. Each object must have:

• role — "system", "user", or "assistant"
• content — a string, or an array of content parts for multimodal inputs (text + image)

The model processes these in order and generates the next turn.

streamboolean

When true, the response is a stream of server-sent events (SSE). Each event contains a ChatCompletionChunk. Also accepts ?stream=true as a query parameter. Default: false.

max_tokensinteger

Maximum number of tokens to generate. The model may stop earlier if a natural stop sequence is reached. Default: 8192.

temperaturenumber

Sampling temperature between 0 and 2. Lower values produce more focused and deterministic output; higher values produce more random output. Default: 0.7.

top_pnumber

Nucleus sampling — only tokens within the cumulative top top_p probability mass are considered. Range: 0 to 1. Default: 0.95. Not recommended to change both temperature and top_p.

ninteger

Number of completion choices to generate for each prompt. Each is a separate ChatMessage in choices[]. Default: 1.

stopstring | string[]

Up to 4 stop sequences. Generation halts when any of these strings is produced. The stop sequence itself is not included in the output.

presence_penaltynumber

Penalises tokens that have appeared at all in the output so far — encouraging the model to explore new topics. Range: -2.0 to 2.0. Default: 0.0.

frequency_penaltynumber

Penalises tokens based on their frequency in the output so far — reducing verbatim repetition. Range: -2.0 to 2.0. Default: 0.0.

logprobsboolean

Whether to return log probabilities of the output tokens. Default: false.

top_logprobsinteger

When logprobs is true, how many top token log probabilities to return per output token. Range: 0 to 20.

toolsChatCompletionTool[]

A list of tools (functions) the model may call. Each tool has type: "function" and a function object with name, description, and parameters (JSON Schema). See Tool Calling below.

tool_choicestring | object

Controls whether and how the model invokes tools. Options:

• "none" — never call tools
• "auto" — model decides (default when tools are present)
• "required" — model must call at least one tool
• { type: "function", function: { name: "..." } } — force a specific function

response_formatobject

Output format hint. { type: "text" } (default) or { type: "json_object" } to guarantee valid JSON output. When using json_object, instruct the model to produce JSON in your system message.

userstring

An end-user identifier for abuse monitoring and usage attribution. This string is never exposed to the model.

Set stream: true. The connection stays open and emits newline-delimited SSE events, each a ChatCompletionChunk. The stream terminates with data: [DONE].

Stream sequence:

1. First chunk — empty delta, carries prompt_filter_results at root level (prompt safety evaluated before generation begins)
2. Mid-stream chunks — delta.content contains incremental text; content_filter_results per choice
3. Final chunk — finish_reason: "stop", empty delta: {}
4. data: [DONE] — sentinel line, not JSON

data: {
  "id": "chatcmpl-DLc8T...",
  "object": "chat.completion.chunk",
  "created": 1774043853,
  "model": "gpt-5-nano-2025-08-07",
  "choices": [{
    "index": 0,
    "delta": { "content": "The " },
    "finish_reason": null,
    "logprobs": null,
    "content_filter_results": {
      "hate":      { "filtered": false, "severity": "safe" },
      "self_harm": { "filtered": false, "severity": "safe" },
      "sexual":    { "filtered": false, "severity": "safe" },
      "violence":  { "filtered": false, "severity": "safe" }
    }
  }]
}

Pass a tools array of function definitions. When the model decides to call one, finish_reason is "tool_calls" and choices[0].message.tool_calls contains the invocation(s). Execute the function locally, then send the result back as a "tool" role message to complete the loop.

Request fields

• tools — array of ChatCompletionTool definitions, each with a function object containing name, description, and parameters (JSON Schema)
• tool_choice — "auto" (default), "none", "required", or { type: "function", function: { name } } to force a specific function

Response fields (Step 1)

• choices[0].finish_reason — will be "tool_calls" when the model wants to invoke a function
• choices[0].message.tool_calls[] — array of ToolCall objects, each with id, function.name, and function.arguments (JSON string)
• choices[0].message.content — null when finish_reason is tool_calls

Response fields (Step 2)

• Returns a normal ChatCompletion with finish_reason: "stop" and the final answer in choices[0].message.content

Possible errors

• INVALID_PARAMETER — malformed tools array or invalid JSON Schema in parameters
• CONTENT_POLICY_VIOLATION — tool call or result blocked by safety policy
• INFERENCE_ERROR — provider rejected the tool-calling request
• INFERENCE_TIMEOUT — agentic loops with many tool turns can exceed the time limit; reduce turns or max_tokens