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

# Create a chat completion

`POST /v1/chat/completions`

Generate an OpenAI-compatible chat completion from conversation messages. Supports streaming, multimodal content, structured outputs, and tool calling.

## Request body

- ChatCompletions
  - `model` string, required — Model identifier to route the request to.
  - `messages` ChatMessage[], required — Conversation history in OpenAI Chat Completions format.
    - `role` string, required — Message role such as system, user, assistant, or tool.
    - `content` union — Message content as a plain string or an array of multimodal content blocks.
      - string
      - union[]
        - union
          - TextContent
            - `type` 'text', required
            - `text` string, required — Plain text content block.
          - ImageContent
            - `type` 'image_url', required
            - `image_url` AppApiV1ChatCompletionsImageUrl, required
              - …
          - FileContent
            - `type` 'file', required
            - `file` File, required
              - …
          - AudioContent
            - `type` 'input_audio', required
            - `input_audio` InputAudio, required
              - …
    - `images` ImageContent[], nullable
      - `type` 'image_url', required
      - `image_url` AppApiV1ChatCompletionsImageUrl, required
        - `url` string, uri, required — Remote URL or data URI for an input image.
        - `detail` 'low' | 'high' | 'auto'
    - `reasoning_details` union[], nullable
      - union
        - ReasoningSummary
          - `id` string, nullable
          - `index` integer, nullable
          - `type` 'reasoning.summary', required
          - `summary` string, required
        - ReasoningEncrypted
          - `id` string, nullable
          - `index` integer, nullable
          - `type` 'reasoning.encrypted', required
          - `data` string, required
        - ReasoningText
          - `id` string, nullable
          - `index` integer, nullable
          - `type` 'reasoning.text', required
          - `text` string, required
    - `name` string
    - `tool_call_id` string
    - `tool_calls` unknown[]
      - unknown
  - `tools` Tool[], nullable
    - `type` 'function', required
    - `function` FunctionDefinition, required
      - `name` string, required — Function name exposed to the model.
      - `description` string, nullable
      - `parameters` object, nullable
      - `strict` boolean, nullable
  - `tool_choice` union
    - string
    - object
  - `response_format` union
    - TextResponseFormat
      - `type` 'text', required
    - JsonObjectResponseFormat
      - `type` 'json_object', required
    - JsonSchemaResponseFormat
      - `type` 'json_schema', required
      - `json_schema` JsonSchemaConfig, required
        - `name` string, required — Name of the JSON schema response format.
        - `description` string
        - `schema` object
        - `strict` boolean
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `stream` boolean, nullable
  - `stream_options` StreamOptions
    - `include_usage` boolean — Include usage in the final streaming chunk.
  - `stop` union
    - string
    - string[]
  - `max_completion_tokens` integer, nullable
  - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
  - `presence_penalty` number, nullable
  - `frequency_penalty` number, nullable
  - `logit_bias` object
  - `parallel_tool_calls` boolean
  - `prediction` Prediction
    - `static_content` StaticContent
      - `content` union, required
        - string
        - unknown[]
          - unknown
      - `type` string, required
  - `web_search_options` object
  - `image_config` ImageConfig
    - `aspect_ratio` '1:1' | '1:4' | '1:8' | '2:3' | '3:2' | '3:4' | '4:1' | '4:3' | '4:5' | '5:4' | '8:1' | '9:16' | '16:9' | '21:9', nullable
    - `image_size` '1K' | '2K' | '4K', nullable

## Response `200`

JSON response when stream=false, or Server-Sent Events when stream=true.

- ChatCompletionResponse
  - `id` string, required
  - `object` 'chat.completion'
  - `created` integer, required
  - `model` string, required
  - `choices` ChatCompletionChoiceResponse[], required
    - `index` integer
    - `message` ChatCompletionMessageResponse, required
      - `role` string, required
      - `content` union
        - string
        - object[]
      - `refusal` string, nullable
      - `tool_calls` ChatCompletionToolCallResponse[], nullable
        - `id` string, nullable
        - `type` 'function'
        - `function` ChatCompletionFunctionCallResponse, required
          - `name` string, nullable
          - `arguments` string
      - `annotations` object[], nullable
      - `reasoning_content` string, nullable
      - `reasoning_details` object[], nullable
      - `images` object[], nullable
      - `name` string, nullable
      - `tool_call_id` string, nullable
    - `finish_reason` string, nullable
    - `logprobs` object, nullable
  - `usage` ChatCompletionUsageResponse
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `prompt_tokens_details` ChatPromptTokensDetailsResponse
      - `cached_tokens` integer, nullable
    - `completion_tokens_details` ChatCompletionTokensDetailsResponse
      - `image_tokens` integer, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `402` — Insufficient credits
- `403` — Forbidden
- `410` — Model deprecated
- `422` — Validation error
- `429` — Rate limited
- `500` — Internal server error
- `503` — Upstream service error

---

[API](https://skmtc.net/naga/apis/nagaai-api.md) · [All operations](https://skmtc.net/naga/apis/nagaai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/naga/nagaai-api/revisions/8bfb4677a79e/schema)