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

# Create a chat completion

`POST /chat/completions`

OpenAI-compatible Chat Completions endpoint. Supports streaming via stream: true, which returns a Server-Sent Events stream of chat.completion.chunk objects.

## Headers

- `Idempotency-Key` string

## Request body

- CreateChatCompletionRequest
  - `model` string, required
  - `messages` ChatCompletionMessage[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool' | 'function' | 'developer', required
    - `content` union
      - string
      - union[]
        - union
          - ChatTextContentPart
            - `type` 'text', required
            - `text` string, required
          - ChatImageContentPart — Image content part. Image input is supported only on multimodal models; see the Models page.
            - `type` 'image_url', required
            - `image_url` object, required
              - …
    - `name` string
    - `tool_calls` object[]
    - `tool_call_id` string
    - `function_call` object
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `max_completion_tokens` integer, nullable
  - `response_format` union
    - ChatResponseFormatText
      - `type` 'text', required
    - ChatResponseFormatJsonSchema
      - `type` 'json_schema', required
      - `json_schema` object, required
        - `name` string, required
        - `description` string
        - `schema` object
        - `strict` boolean
  - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
  - `n` 1 — Only n=1 is currently supported.
  - `modalities` string[]
  - `stream` boolean — When true, the response is returned as a Server-Sent Events stream of chat.completion.chunk objects instead of a single JSON response.
  - `stream_options` object — Options that apply when stream is true.
    - `include_usage` boolean — When true, emit a final chunk with token usage for the full request before the [DONE] terminator.
  - `store` true — Only true is supported.
  - `user` string
  - `metadata` RequestMetadata — Optional string metadata. completion_window controls scheduling; completion_webhook/webhook_token configure completion webhooks.
    - `completion_window` 'asap' | 'priority' | 'standard' | 'flex' — [Completion window](/completion-windows) (i.e. latency tier) for the request. Support matrix is available on the [Pricing](/pricing) page. When omitted, defaults to `standard` if that window is supported for the model; otherwise `flex` for async requests when the model supports it, and `asap` in all other cases. See [default behavior](/completion-windows#default-behavior).
    - `completion_webhook` string, uri
    - `webhook_token` string

## Response `200`

Chat completion. Returns a single JSON object by default, or a Server-Sent Events stream of chat.completion.chunk objects when stream: true (terminated by a final data: [DONE] line).

- ChatCompletionResponse
  - `id` string, required
  - `object` 'chat.completion', required
  - `created` integer, required
  - `model` string, required
  - `choices` ChatCompletionChoice[], required
    - `index` integer, required
    - `message` ChatCompletionResponseMessage, required
      - `role` 'assistant', required
      - `content` string, nullable, required
      - `reasoning_content` string, nullable
      - `refusal` string, nullable
    - `logprobs` unknown, required
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call', required
  - `usage` ChatCompletionUsage
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `prompt_tokens_details` object
    - `completion_tokens_details` object

## Other responses

- `400` — Invalid request or unsupported feature.
- `401` — Authentication error.
- `408` — Timed out waiting for completion.
- `500` — Server error.

---

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