---
title: "Create chat completion"
method: POST
path: "/chat/completions"
---

# Create chat completion

`POST /chat/completions`

Creates a model response for the given chat conversation.

## Headers

- `Authorization` string, required
- `Content-Type` string, required
- `x-show-additional-info` 'true' | 'false'

## Request body

- ChatCompletionRequest
  - `model` 'interfaze-beta', required — Model id to use. Currently the only supported value is `interfaze-beta`.
  - `messages` Message[], required — A list of messages making up the conversation so far.
    - `role` 'system' | 'user' | 'assistant' | 'tool', required — The role of the message author.
    - `content` union, required — The message content. Either a plain string or an array of content parts for multimodal input.
      - string
      - ContentPart[]
        - union — A typed content part for multimodal input. Discriminated by `type`.
          - TextPart
            - `type` 'text', required — Must be `"text"`.
            - `text` string, required — The text content.
          - ImagePart
            - `type` 'image_url', required — Must be `"image_url"`.
            - `image_url` object, required — Wrapper object containing the image source.
              - …
          - FilePart
            - `type` 'file', required — Must be `"file"`.
            - `file` object, required — Wrapper object containing the file source.
              - …
    - `name` string — Optional name of the participant.
    - `tool_calls` ToolCall[] — Assistant-only. Tool calls the model wants the caller to execute.
      - `id` string, required — Unique id for this tool call.
      - `type` 'function', required
      - `function` object, required
        - `name` string, required — The function name to call.
        - `arguments` string, required — JSON-encoded arguments for the function.
    - `tool_call_id` string — Tool-message-only. The id of the tool call this message is responding to.
  - `stream` boolean — If `true`, partial message deltas are sent as server-sent events. The stream terminates with `data: [DONE]`.
  - `response_format` union — Constrains the model output to a specific format. Follows the [OpenAI structured output specification](https://developers.openai.com/api/docs/guides/structured-outputs?api-mode=chat).
    - object
      - `type` 'text', required — Default — plain text output.
    - object
      - `type` 'json_schema', required — JSON schema–constrained output.
      - `json_schema` object, required — The JSON schema configuration.
        - `name` string, required — Identifier for the schema (e.g. `"id_schema"`).
        - `schema` object, required — A valid JSON Schema definition describing the output shape.
        - `strict` boolean — Whether to strictly enforce the schema.
  - `tools` Tool[] — A list of tools (functions) the model may call. Follows the [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling?api-mode=chat) schema.
    - `type` 'function', required — Always `"function"`.
    - `function` ToolFunction, required — The function definition for a tool.
      - `name` string, required — Unique function name (snake_case recommended).
      - `description` string — What the function does. Helps the model decide when to call it.
      - `parameters` object — JSON Schema describing the function's arguments.
  - `tool_choice` union — Controls which (if any) tool the model calls. `"auto"` = model decides, `"none"` = no tool calls, `"required"` = must call at least one tool, or an object to force a specific function.
    - 'auto' | 'none' | 'required'
    - object
      - `type` 'function', required
      - `function` object, required
        - `name` string, required — The name of the function to force.
  - `reasoning_effort` 'low' | 'medium' | 'high' — Enables extended reasoning. The model spends more compute and thinking tokens before producing a final answer. `low` = light reasoning pass, `medium` = moderate reasoning, `high` = deep reasoning (recommended for math, science, complex agents). When set, the response contains a `reasoning` field. In streaming mode, reasoning tokens stream first inside `<think>...</think>` tags. Off by default.
  - `max_tokens` integer — Maximum number of tokens to generate in the completion. Hard upper bound of 32,000 tokens.
  - `temperature` number — Sampling temperature between `0` and `2`. Higher values produce more random output, lower values make the output more focused and deterministic.
  - `top_p` number — Nucleus sampling. The model considers only the tokens whose cumulative probability mass is `top_p`. `0.1` means only the top 10% of probability mass is sampled from. Generally only adjust one of `temperature` or `top_p`.

## Response `200`

Successful chat completion response.

- ChatCompletionResponse — A successful non-streaming chat completion response.
  - `id` string — Unique identifier for the completion.
  - `object` 'chat.completion' — Always `chat.completion`.
  - `model` string — The model used.
  - `choices` Choice[] — A list of completion choices.
    - `index` integer — The index of this choice in the `choices` array.
    - `message` Message — A single message in the conversation.
      - `role` 'system' | 'user' | 'assistant' | 'tool', required — The role of the message author.
      - `content` union, required — The message content. Either a plain string or an array of content parts for multimodal input.
        - string
        - ContentPart[]
          - union — A typed content part for multimodal input. Discriminated by `type`.
            - TextPart
              - …
            - ImagePart
              - …
            - FilePart
              - …
      - `name` string — Optional name of the participant.
      - `tool_calls` ToolCall[] — Assistant-only. Tool calls the model wants the caller to execute.
        - `id` string, required — Unique id for this tool call.
        - `type` 'function', required
        - `function` object, required
          - `name` string, required — The function name to call.
          - `arguments` string, required — JSON-encoded arguments for the function.
      - `tool_call_id` string — Tool-message-only. The id of the tool call this message is responding to.
    - `finish_reason` 'stop' | 'length' | 'tool_calls' — The reason the model stopped generating. `stop` = natural end or stop sequence, `length` = max tokens reached, `tool_calls` = model wants to call a tool.
  - `usage` Usage — Token usage statistics.
    - `prompt_tokens` integer — Number of tokens in the prompt.
    - `completion_tokens` integer — Number of tokens in the completion.
    - `total_tokens` integer — Total tokens used (prompt + completion).
  - `reasoning` string — Present when `reasoning_effort` is set. The model's thinking trace.
  - `precontext` PrecontextEntry[] — Raw outputs from any internal tasks the model ran (OCR, STT, web search, etc.).
    - `name` string — The task that produced this result (e.g. `ocr`, `stt`, `translate`, `web_search`, `scraper`, `object_detection`, `guardrails`, `code_sandbox`).
    - `result` unknown
  - `vcache` boolean — Whether the response was served from the model's verified cache.

## Other responses

- `400` — The request body is malformed or missing required fields.
- `401` — The API key is missing, invalid, or revoked.
- `402` — Your account has insufficient credits.
- `413` — Request body or input file exceeds size limits.
- `429` — You exceeded the rate limit. Retry with exponential backoff.
- `500` — Server-side failure. Safe to retry.
- `503` — Temporary capacity issue. Retry with backoff.

---

[API](https://skmtc.dev/interfaze/apis/interfaze-api.md) · [All operations](https://skmtc.dev/interfaze/apis/interfaze-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/interfaze/interfaze-api/revisions/b6d1b8e00301/schema)