> ## Documentation Index
> Fetch the complete documentation index at: https://doc.octopusx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions API (Default Streaming)

> Start a conversation using the OpenAI Chat Completions-compatible format and return model output via SSE streaming.

# Chat Completions API (Default Streaming)

Use a unified conversation format to call upstream models such as OpenAI, Claude, Gemini, DeepSeek, and Qwen. This document uses streaming output as the default, making it suitable for chat, Agent, and long-text generation scenarios where output needs to be displayed as it is generated.

<Info>
  If `stream` is not provided in this project's route, it is handled as non-streaming. If you want to always receive a streaming response, explicitly pass `"stream": true`.
</Info>

## Request Body

<ParamField body="model" type="string" required>
  Model name. You can check the models available to the current API Key via [Model List](./models).
</ParamField>

<ParamField body="messages" type="array<object>" required>
  Conversation messages arranged in chronological order. Common roles are `system`, `user`, `assistant`, and `tool`.
</ParamField>

<ParamField body="messages[].content" type="string | array" required>
  Message content. A string indicates plain text; an array indicates multimodal content and supports `text`, `image_url`, `input_audio`, `file`, and `video_url`.
</ParamField>

<ParamField body="stream" type="boolean" required>
  When set to `true`, the response is `text/event-stream`, with each chunk pushed as `data:` and `data: [DONE]` returned at the end.
</ParamField>

<ParamField body="stream_options.include_usage" type="boolean">
  Includes token usage statistics in the last message of the stream. Supported by only some upstream models.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Limits the maximum number of generated tokens. For some reasoning models, it is recommended to use `max_completion_tokens` instead.
</ParamField>

<ParamField body="max_completion_tokens" type="integer">
  Limits the maximum number of completion tokens, including reasoning tokens. Suitable for models that support reasoning.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature, commonly in the range `0` to `2`. Lower values are more stable, higher values are more diverse.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling parameter, commonly in the range `0` to `1`. It is generally not recommended to adjust `temperature` and `top_p` significantly at the same time.
</ParamField>

<ParamField body="tools" type="array<object>">
  Function-calling tool list, compatible with OpenAI `tools`.
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controls whether the model calls tools. Common values are `auto`, `none`, and `required`; you can also specify a particular function.
</ParamField>

<ParamField body="response_format" type="object">
  Specifies the output format, such as `{ "type": "json_object" }` or `json_schema`.
</ParamField>

<ParamField body="reasoning_effort" type="string">
  Reasoning effort. Common values are `low`, `medium`, and `high`; whether it takes effect depends on the model.
</ParamField>

## Request Example

<RequestExample>
  ```bash theme={null}
  curl -N -X POST https://octopusx.ai/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [
        { "role": "system", "content": "You are a concise technical assistant." },
        { "role": "user", "content": "Explain the role of an API gateway in three points." }
      ],
      "stream": true,
      "stream_options": {
        "include_usage": true
      }
    }'
  ```
</RequestExample>

### Multimodal Streaming

```bash theme={null}
curl -N -X POST https://octopusx.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Summarize the main conclusions of this chart." },
          { "type": "image_url", "image_url": { "url": "https://.../chart.png", "detail": "high" } }
        ]
      }
    ],
    "stream": true
  }'
```

## Response Example

<ResponseExample>
  ```text 200 theme={null}
  data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1735689600,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":"API"},"finish_reason":null}]}

  data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1735689600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" gateway"},"finish_reason":null}]}

  data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1735689600,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":26,"completion_tokens":38,"total_tokens":64}}

  data: [DONE]
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "field model is required",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "Insufficient user quota",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "The current request rate is too high. Please try again later.",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="id" type="string">
  The response ID generated for this request.
</ResponseField>

<ResponseField name="object" type="string">
  The streaming response is always `chat.completion.chunk`.
</ResponseField>

<ResponseField name="choices[].delta" type="object">
  Incremental content. May include `role`, `content`, `reasoning_content`, or `tool_calls`.
</ResponseField>

<ResponseField name="choices[].finish_reason" type="string">
  Reason for completion. Common values are `stop`, `length`, and `tool_calls`.
</ResponseField>

<ResponseField name="usage" type="object">
  Usage statistics. It is guaranteed to appear only when the upstream returns usage data and `stream_options.include_usage` is enabled.
</ResponseField>

## Related APIs

* [Chat Completions API (Default Non-Streaming)](./chat-completions-non-stream)
* [OpenAI Multimodal Responses API](./openai-responses)
* [Model List](./models)