---
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.hotapi.ai`
- URL: `https://api.hotapi.ai/v1/chat/completions`
- Auth: HTTP bearer

OpenAI-compatible chat completion. The synchronous response is a standard chat-completion object. Set stream: true to receive Server-Sent Events as standard OpenAI `chat.completion.chunk` objects — `delta.content` / `delta.reasoning` / `delta.tool_calls` fragments, a terminal frame carrying `finish_reason`, then a usage frame (`choices: []` + token counts), then `data: [DONE]`. Tool calls (function calling) are passed through verbatim: send `tools` as you would to OpenAI and accumulate streamed `delta.tool_calls` by `index`. A mid-stream model failure arrives as an `{"error":{...}}` frame (the stream status was already committed as 200) and still refunds the full estimate — there is no OpenAI-standard error frame after the 200. The customer is charged an upper-bound estimate before the call, and the actual usage is reconciled when the model responds — successful responses refund the unused estimate to the exact wallet buckets it was drawn from; failed / stream-error responses refund the full estimate. Serving-account faults we cannot let you fix return **503** with a `Retry-After` header (the affected serving account is on a short cooldown — retry after it); model overload is **502**; your own rate limit is **429** with `code: rpm_exceeded`, while a passed-through model throttle always carries a different code.

## Request body

- ChatCompletionRequest: OpenAI-compatible chat completion request. Extra OpenAI parameters are accepted and forwarded.
  - `model` string, required
  - `messages` object[], required
    - `role` union, required
      - 'system'
      - 'user'
      - 'assistant'
      - 'tool'
    - `content` string, nullable, required
    - `reasoning` string: Reasoning trace, present on assistant messages when the model emits one (thinking mode).
    - `tool_calls` object[]
      - `id` string, required
      - `type` 'function', required
      - `function` object, required
        - `name` string, required
        - `arguments` string, required
    - `tool_call_id` string: Id of the tool call this result answers (role: "tool").
    - `name` string
  - `stream` boolean: Stream the response as SSE (`text/event-stream`).
  - `max_tokens` integer
  - `temperature` number

## Response `200`

OpenAI-compatible chat completion (non-streaming). When `stream: true`, the response is instead an SSE stream of standard `chat.completion.chunk` objects: `choices[0].delta` fragments (`content`, `reasoning`, `tool_calls`), a terminal frame with `finish_reason`, a usage frame with empty `choices`, then `data: [DONE]`.

- ChatCompletionResponse: OpenAI-compatible chat completion (non-streaming). When `stream: true`, the response is instead an SSE stream of standard `chat.completion.chunk` objects: `choices[0].delta` fragments (`content`, `reasoning`, `tool_calls`), a terminal frame with `finish_reason`, a usage frame with empty `choices`, then `data: [DONE]`.
  - `id` string, required
  - `object` 'chat.completion', required
  - `created` integer, required: Unix seconds.
  - `model` string, required
  - `choices` object[], required
    - `index` integer, required
    - `message` object, required
      - `role` union, required
        - 'system'
        - 'user'
        - 'assistant'
        - 'tool'
      - `content` string, nullable, required
      - `reasoning` string: Reasoning trace, present on assistant messages when the model emits one (thinking mode).
      - `tool_calls` object[]
        - `id` string, required
        - `type` 'function', required
        - `function` object, required
          - `name` string, required
          - `arguments` string, required
      - `tool_call_id` string: Id of the tool call this result answers (role: "tool").
      - `name` string
    - `finish_reason` string, nullable, required
  - `usage` object, required
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required

## Other responses

- `400`: Standard error envelope returned by every error response (OpenAI-style).
- `401`: Standard error envelope returned by every error response (OpenAI-style).
- `402`: Standard error envelope returned by every error response (OpenAI-style).
- `429`: Standard error envelope returned by every error response (OpenAI-style).
- `502`: Standard error envelope returned by every error response (OpenAI-style).
- `503`: Standard error envelope returned by every error response (OpenAI-style).

---

[API](https://skmtc.dev/hotapi/apis/hotapi-gateway.md) · [All operations](https://skmtc.dev/hotapi/apis/hotapi-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/hotapi/apis/hotapi-gateway/revisions/9b6578b0c389?raw)