# Chat Completions

> 透過 LLMoxy 使用 OpenAI 相容的 Chat Completions 介面。

`POST /v1/chat/completions` 是主要的 OpenAI 相容聊天介面。

```bash
curl https://llmoxy.com/v1/chat/completions \
  -H "Authorization: Bearer <LLMOXY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "messages": [
      { "role": "system", "content": "Be concise." },
      { "role": "user", "content": "What is LLMoxy?" }
    ]
  }'
```

## 請求體

常用欄位：

| 欄位 | 說明 |
| --- | --- |
| `model` | 必填，模型 ID。 |
| `messages` | 必填，對話訊息陣列。 |
| `temperature`, `top_p`, `n`, `stop` | 採樣控制參數，會傳給相容的上游。 |
| `max_tokens`, `max_completion_tokens` | 輸出 Token 限制。 |
| `stream` | 設定為 `true` 啟用 SSE 流式輸出。 |
| `stream_options.include_usage` | 上游支援時在流式響應中返回 usage。 |
| `tools`, `tool_choice` | OpenAI 相容工具呼叫。 |
| `response_format` | 對支援的模型請求結構化輸出。 |
| `reasoning_effort` | 支援推理的模型可使用 `low`、`medium`、`high`。 |
| `modalities`, `audio` | 支援多模態音訊的模型可使用。 |
| `user` | 可選，用於你自己的終端使用者標識。 |

不同模型支援的參數不同。如果響應裡出現某個參數不被支援，請移除該參數或改用其他模型。

## 流式輸出

```json
{
  "model": "grok-4.7",
  "stream": true,
  "messages": [
    { "role": "user", "content": "Stream one sentence." }
  ]
}
```

響應使用 OpenAI 風格 SSE chunk，並以 `[DONE]` 結束。

## 工具呼叫

```json
{
  "model": "grok-4.7",
  "messages": [
    { "role": "user", "content": "What is the weather in Singapore?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    }
  ]
}
```

支援工具呼叫的模型會接收工具定義並返回 OpenAI 相容的工具呼叫響應。

## 舊 Completions

舊文字補全客戶端可使用 `POST /v1/completions`。

本文是 https://tw.llmoxy.com/docs/api-reference/chat-completions 的 markdown 版本。
