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

# Chat completions

`POST /chat/completions`

OpenAI-compatible chat completions.

Text-only requests are allowed. To reference live stream media, put
`ovs://streams/<id>?...` inside an `image_url` or `video_url` content part. Unknown
fields are accepted for SDK compatibility.

Set `stream: true` to receive `text/event-stream`. When
`stream_options.include_usage` is also `true`, the stream may include a final
usage chunk.

## Headers

- `X-Overshoot-Region` 'us-west1' | 'us-central1'

## Request body

- ChatCompletionRequest — OpenAI-compatible. Permissive — unknown fields are accepted for SDK compatibility. To reference a stream's frames, include `video_url` or `image_url` content parts whose URL uses the `ovs://streams/{stream_id}?...` reference scheme.
  - `model` string, required — Model identifier from `GET /models`. Must be `ready` at request time.
  - `messages` ChatMessage[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool', required
    - `content` union, required
      - string
      - ContentPart[]
        - union
          - TextPart
            - `type` 'text', required
            - `text` string, required
          - ImageUrlPart
            - `type` 'image_url', required
            - `image_url` object, required
              - …
          - VideoUrlPart
            - `type` 'video_url', required
            - `video_url` object, required
              - …
  - `max_completion_tokens` integer, nullable — Optional output-token cap. OpenAI's preferred name.
  - `max_tokens` integer, nullable — Legacy alias for `max_completion_tokens`.
  - `response_format` object — Used when supported by the selected model/provider.
  - `stream` boolean — When `true`, the response is a server-sent event stream.
  - `stream_options` object — Only meaningful when `stream: true`.
    - `include_usage` boolean — When `true`, the stream may include a final usage chunk.
  - `tools` object[] — OpenAI-style tool definitions.
  - `tool_choice` union — OpenAI-style tool choice.
    - string
    - object
  - `parallel_tool_calls` boolean — OpenAI-style parallel tool-call setting.
  - `thread_id` string, nullable — Optional key for prompt-cache reuse across related requests in the same user conversation and model. See the Prompt cache guide.

## Response `200`

Completion response. JSON by default; if the request sets `stream: true`,
the response is an OpenAI-style SSE stream (`text/event-stream`) terminated by
`data: [DONE]`.

- ChatCompletionResponse
  - `id` string, required
  - `object` string, required
  - `created` integer, required
  - `model` string, required
  - `choices` ChatCompletionChoice[], required
    - `index` integer, required
    - `message` object, required
      - `role` string, required
      - `content` string, nullable
      - `tool_calls` object[] — OpenAI-style tool calls. Present when the model emits any.
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter', nullable
  - `usage` ChatCompletionUsage
    - `prompt_tokens` integer — Tokens in the request — text plus visual tokens from any frames or segments.
    - `completion_tokens` integer
    - `total_tokens` integer
  - `overshoot` OvershootMetadata — Overshoot-specific response metadata. Observability only.
    - `cache` object
      - `thread_id` string, nullable — The `thread_id` you supplied, or `null`.
      - `cache_hit` boolean — `true` when cached prompt tokens were reported.
      - `cached_input_tokens` integer — Prompt tokens served from prefix cache.

## Other responses

- `400` — Invalid stream URL/query, invalid segment, unsupported model/media combination, or provider safety block.
- `401` — Missing or invalid bearer API key.
- `402` — Billing denied inference.
- `403` — Valid key, but the requested resource belongs to another user.
- `404` — Stream missing, stream deleted, lease expired, no retained frames matched, or pricing/model resource not found.
- `409` — Wrong region, multiple stream regions, or requested lifetime frame index has not arrived yet.
- `410` — Requested exact lifetime frame index has been evicted.
- `422` — Request validation failed.
- `429` — Per-user inference rate limit exceeded, or the model provider rate-limited the request.
- `500` — Internal processing error.
- `502` — Model provider request failed, unauthorized, or returned a server error.
- `503` — Service temporarily unavailable.
- `504` — Model provider request timed out.

---

[API](https://skmtc.net/overshoot/apis/overshoot-api.md) · [All operations](https://skmtc.net/overshoot/apis/overshoot-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/overshoot/overshoot-api/versions/defe49d6c837/schema)