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

# Create chat completion

`POST /chat/completions`

Creates a model response for the given chat conversation.

The conversation is provided as an array of messages, where each message has a `role` (system, user, assistant, or tool) and `content`.

Set `stream: true` to receive partial responses as server-sent events.

## Request body

- ChatCompletionRequest — Request body for chat completions.
  - `frequency_penalty` number, float, nullable — Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far.
  - `max_tokens` integer, nullable — The maximum number of tokens to generate in the chat completion.
  - `messages` ChatMessage[], required — A list of messages comprising the conversation so far.
    - `content` string, nullable — The content of the message.
    - `name` string, nullable — The name of the author (for function/tool messages).
    - `role` string, required — The role of the message author (system, user, assistant, tool, function).
    - `tool_call_id` string, nullable — The ID of the tool call this message is responding to.
    - `tool_calls` ToolCall[], nullable — Tool calls made by the assistant.
      - `function` FunctionCall, required — A function call within a tool call.
        - `arguments` string, required — The arguments to pass to the function, as a JSON string.
        - `name` string, required — The name of the function to call.
      - `id` string, required — The ID of the tool call.
      - `type` string, required — The type of tool (currently only "function").
  - `model` string, required — ID of the model to use.
  - `n` integer, nullable — How many chat completion choices to generate for each input message.
  - `presence_penalty` number, float, nullable — Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far.
  - `stop` string[], nullable — Up to 4 sequences where the API will stop generating further tokens.
  - `stream` boolean, nullable — If set, partial message deltas will be sent as server-sent events.
  - `temperature` number, float, nullable — What sampling temperature to use, between 0 and 2.
  - `tool_choice` unknown
  - `tools` Tool[], nullable — A list of tools the model may call.
    - `function` FunctionDefinition, required — Definition of a function that can be called by the model.
      - `description` string, nullable — A description of what the function does.
      - `name` string, required — The name of the function.
      - `parameters` unknown
    - `type` string, required — The type of tool (currently only "function").
  - `top_p` number, float, nullable — An alternative to sampling with temperature, called nucleus sampling.
  - `user` string, nullable — A unique identifier representing your end-user.

## Response `200`

Chat completion generated successfully. When streaming, returns a series of SSE events.

- ChatCompletionResponse — Response from chat completions.
  - `choices` ChatChoice[], required — A list of chat completion choices.
    - `finish_reason` string, nullable — The reason the model stopped generating tokens.
    - `index` integer, required — The index of the choice in the list of choices.
    - `message` ChatMessage, required — A message in a chat conversation.
      - `content` string, nullable — The content of the message.
      - `name` string, nullable — The name of the author (for function/tool messages).
      - `role` string, required — The role of the message author (system, user, assistant, tool, function).
      - `tool_call_id` string, nullable — The ID of the tool call this message is responding to.
      - `tool_calls` ToolCall[], nullable — Tool calls made by the assistant.
        - `function` FunctionCall, required — A function call within a tool call.
          - `arguments` string, required — The arguments to pass to the function, as a JSON string.
          - `name` string, required — The name of the function to call.
        - `id` string, required — The ID of the tool call.
        - `type` string, required — The type of tool (currently only "function").
  - `created` integer, required — The Unix timestamp of when the chat completion was created.
  - `id` string, required — A unique identifier for the chat completion.
  - `model` string, required — The model used for the chat completion.
  - `object` string, required — The object type, always "chat.completion".
  - `system_fingerprint` string, nullable — The system fingerprint of the model.
  - `usage` Usage — Token usage statistics.
    - `completion_tokens` integer, required — Number of tokens in the generated completion.
    - `prompt_tokens` integer, required — Number of tokens in the prompt.
    - `total_tokens` integer, required — Total number of tokens used in the request.

## Other responses

- `400` — Invalid request — check that your messages array is properly formatted and all required fields are present.
- `401` — Invalid or missing API key. Ensure your `Authorization` header is set to `Bearer YOUR_API_KEY`.
- `402` — Insufficient credits. Top up your account to continue making requests.
- `403` — Your API key does not have access to the requested model.
- `404` — The specified model does not exist. Use `GET /models` to list available models.
- `429` — Rate limit exceeded. Back off and retry after a short delay.
- `500` — An unexpected error occurred. Retry the request or contact support if the issue persists.

---

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