---
title: "Create a chat completion"
method: POST
path: "/v1/chat/completions"
tags: ["Chat"]
---

# Create a chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.inceptionlabs.ai`
- URL: `https://api.inceptionlabs.ai/v1/chat/completions`
- Auth: HTTP bearer

Generate a chat completion from a sequence of messages. Returns a `ChatCompletion` object, or a server-sent events stream of `ChatCompletionChunk` deltas when `stream=true`. Supports tool calling, structured output via `response_format`, and reasoning controls.

## Request body

- ChatCompletionRequest
  - `messages` Message[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool' | 'function', required: The role of the message sender (system, user, assistant, tool, function).
    - `content` union: A string or array of content parts. Models with image support accept user-message parts of the form {"type": "image_url", "image_url": {"url": "data:image/png;base64,...", "detail": "auto"}} alongside text parts. Images must be base64 PNG, JPEG, WebP, or GIF data URLs, at most 10 MiB each and 15 MiB total per request. Detail is optional (auto, low, high). Remote URLs are not supported.
      - string
      - object[]
    - `tool_calls` ToolCall[], nullable: The tool calls generated by the model.
      - `index` integer, nullable
      - `id` string, required
      - `type` 'function', required
      - `function` FunctionCall, required
        - `name` string, nullable
        - `arguments` string, required
    - `tool_call_id` string, nullable: The ID of the tool call this message is responding to (for role='tool').
  - `model` string, required: The model to use for the chat completion.
  - `max_tokens` integer: Maximum number of tokens to generate. Deprecated in favour of `max_completion_tokens`, which takes precedence when both are supplied. The maximum depends on `model`: 50,000 for `mercury-2`; 65,536 for `mercury-2.5`; 131,072 for `mercury-3`. When neither token-budget field is supplied: For `mercury-2`, the default is 16,384. For `mercury-2.5`, the default is 16,384; 65,536 when `reasoning_effort="high"`. For `mercury-3`, the default is 24,576; 8,192 when `reasoning_effort="instant"`; 65,536 when `reasoning_effort="medium"`; 131,072 when `reasoning_effort="high"`.
  - `max_completion_tokens` integer: An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. Supersedes `max_tokens`. When neither field is supplied, the model's configured default applies (16384 for `mercury-2`). The maximum depends on `model`: 50,000 for `mercury-2`; 65,536 for `mercury-2.5`; 131,072 for `mercury-3`. When neither token-budget field is supplied: For `mercury-2`, the default is 16,384. For `mercury-2.5`, the default is 16,384; 65,536 when `reasoning_effort="high"`. For `mercury-3`, the default is 24,576; 8,192 when `reasoning_effort="instant"`; 65,536 when `reasoning_effort="medium"`; 131,072 when `reasoning_effort="high"`.
  - `temperature` number: What sampling temperature to use, between 0.5 and 1. Higher values make the output more random; lower values make it more focused and deterministic. For `mercury-2`, the default is 0.75; out-of-range values are reset to 0.75 with a `warning` in the response. For `mercury-2.5`, the default is 1; out-of-range values are reset to 1 with a `warning` in the response. For `mercury-3`, the default is 1; out-of-range values are reset to 1 with a `warning` in the response.
  - `stop` string[]: A list of sequences where the API will stop generating further tokens. The returned text will not contain the stop sequences.
  - `tools` ChatCompletionTool[]: A list of tools the model may call. Use this to provide functions the model can generate JSON arguments for.
    - `type` 'function', required: The type of the tool.
    - `function` FunctionDefinition, required
      - `name` string, required: The name of the function to call. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
      - `description` string: A description of what the function does, used by the model to choose when and how to call the function.
      - `parameters` object: The parameters the function accepts, described as a JSON Schema object.
      - `strict` boolean: Whether to enforce strict schema adherence when generating the function call. When true, the model output is constrained to match the `parameters` schema exactly.
  - `tool_choice` union: Controls tool selection: 'auto' (model decides, default when tools present), 'required' (model must call one), 'none' (model must not call one), or {"type": "function", "function": {"name": "..."}} to force one declared tool.
    - 'auto' | 'required' | 'none'
    - NamedToolChoice: Forces one declared tool: {"type": "function", "function": {"name": "..."}}.
      - `type` 'function', required: Always `function`.
      - `function` ToolChoiceFunction, required: The `function` object of a named tool_choice.
        - `name` string, required: Name of the tool the model must call. Must match a tool in `tools`.
  - `stream` boolean: Whether to stream the response.
  - `stream_options` StreamOptions: Options for controlling streaming behavior. Only used when `stream=true`.
    - `include_usage` boolean: If true, an additional chunk is streamed before the `data: [DONE]` message containing the token usage statistics for the entire request. Inside that chunk, `choices` is an empty array and the `usage` field is populated.
  - `diffusing` boolean: Whether to show the diffusion effect in the streamed response.
  - `extra_body` object: Extra parameters passed to the model (OpenAI-compat passthrough).
  - `realtime` boolean: Enable flag for more realtime workloads that require lower TTFT/TTFAT.
  - `response_format` union: An object specifying the format that the model must output.
    - ResponseFormatText
      - `type` 'text', required: The type of response format being defined. Always `text`. The model responds with plain text and output is not constrained to JSON.
    - ResponseFormatJSONObject
      - `type` 'json_object', required: The type of response format being defined. Always `json_object`.
    - ResponseFormatJSONSchema
      - `type` 'json_schema', required: The type of response format being defined. Always `json_schema`.
      - `json_schema` JSONSchema, required
        - `name` string, required: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
        - `description` string: A description of what the response format is for, used by the model to determine how to respond in the format.
        - `schema` object: The schema for the response format, described as a JSON Schema object.
        - `strict` boolean: Whether to enforce strict schema adherence when generating the output. When true, the model output is constrained to match the supplied `schema` exactly.
  - `reasoning_summary` boolean: Request a summary of the model's reasoning process.
  - `reasoning_summary_wait` boolean: Wait for all reasoning summaries to complete before finishing the response.
  - `reasoning_effort` 'instant' | 'low' | 'medium' | 'high': Constrains the effort spent on reasoning before the model responds.

## Response `200`

Successful response. Returns a JSON object when `stream=false`, or a server-sent events stream of `ChatCompletionChunk` objects (terminated by `data: [DONE]`) when `stream=true`.

- ChatCompletionResponse
  - `id` string, required
  - `object` 'chat.completion', required
  - `created` integer, required
  - `model` string, required
  - `choices` Choice[], required
    - `index` integer, required
    - `message` Message, required
      - `role` 'system' | 'user' | 'assistant' | 'tool' | 'function', required: The role of the message sender (system, user, assistant, tool, function).
      - `content` union: A string or array of content parts. Models with image support accept user-message parts of the form {"type": "image_url", "image_url": {"url": "data:image/png;base64,...", "detail": "auto"}} alongside text parts. Images must be base64 PNG, JPEG, WebP, or GIF data URLs, at most 10 MiB each and 15 MiB total per request. Detail is optional (auto, low, high). Remote URLs are not supported.
        - string
        - object[]
      - `tool_calls` ToolCall[], nullable: The tool calls generated by the model.
        - `index` integer, nullable
        - `id` string, required
        - `type` 'function', required
        - `function` FunctionCall, required
          - `name` string, nullable
          - `arguments` string, required
      - `tool_call_id` string, nullable: The ID of the tool call this message is responding to (for role='tool').
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'null', nullable, required: The reason the model stopped generating tokens.
  - `usage` Usage, required
    - `prompt_tokens` integer, required: Number of tokens in the prompt.
    - `completion_tokens` integer, required: Number of tokens in the generated completion, including reasoning tokens.
    - `total_tokens` integer, required: Total tokens used in the request (prompt + completion).
    - `prompt_tokens_details` PromptTokensDetails, required: Breakdown of the tokens in the prompt.
      - `cached_tokens` integer: Prompt tokens served from the prefix cache.
    - `completion_tokens_details` CompletionTokensDetails, required: Breakdown of the tokens generated for the completion.
      - `reasoning_tokens` integer: Tokens generated by the model for reasoning.
  - `warning` string, nullable
  - `reasoning_summary` ReasoningSummary: Summary of the model's reasoning process.
    - `content` string, nullable: The summarized reasoning.
    - `status` 'complete' | 'unavailable' | 'skipped': Status of the summary.

## Other responses

- `400`: Bad Request — invalid parameters.
- `401`: Unauthorized — missing or invalid API key.
- `402`: Payment Required — billing inactive or quota exceeded.
- `404`: Not Found — model not available for this account.
- `429`: Too Many Requests — rate limit exceeded.
- `500`: Internal Server Error.

## Changes

- **2026-11-03** `9d854458fa76`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/inceptionlabs/apis/inception-api/changes/v1/chat/completions/post.md)

---

[API](https://skmtc.dev/inceptionlabs/apis/inception-api.md) - [All operations](https://skmtc.dev/inceptionlabs/apis/inception-api/llms.txt) - [OpenAPI document](https://skmtc.dev/inceptionlabs/apis/inception-api/revisions/9d854458fa76?raw)