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

# 建立對話請求 (OpenAI)

> 通用文字對話介面，支援 OpenAI 相容的大型語言模型生成對話回覆

## 簡介

通用文字對話介面，支援 OpenAI 相容的大型語言模型生成對話回覆。透過統一的 API 介面，您可以呼叫 OpenAI、Claude、DeepSeek、Grok、通義千問等多個主流大型模型。

> [!NOTE]
>
> `gpt-6.1-sol`：函式呼叫和 `reasoning.effort="max"` 使用 Responses。Chat Completions 支援不帶工具的請求，`reasoning_effort` 可用值為 `low`、`medium`、`high`、`xhigh`。兩種介面均不支援 `none` 或 `minimal`，不要傳入 `temperature`、`top_p` 或 logprobs 相關欄位。詳見 [GPT 6.1 Sol](/docs/zh-Hant/model-api/openai/gpt-6.1-sol)。

## 認證

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 請求參數

**model** `string` *required*

模型識別碼，對應模型廣場。

> [!TIP]
>
> mixroute 支援多種模型，完整模型列表見 [模型廣場](https://console.mixroute.ai/models)。

**messages** `array` *required*

對話訊息列表，每個元素包含 `role`（user/system/assistant）和 `content`

**temperature** `number`

隨機性控制，0-2，數值越高回覆越隨機

**stream** `boolean`

是否啟用串流輸出，回傳 SSE 格式的分片資料

**max\_tokens** `integer`

最大生成 token 數，控制回覆長度

**response\_format** `object`

輸出格式，支援 `text` 或 `json_object` / `json_schema`

**top\_p** `number`

核採樣參數，0-1，替代 temperature 使用，數值越低採樣越保守

**frequency\_penalty** `number`

頻率懲罰，-2 到 2，正值根據已有頻率減少重複 token

**presence\_penalty** `number`

存在懲罰，-2 到 2，正值鼓勵討論新話題

**stop** `string | array`

停止序列，遇到指定字串時停止生成

**seed** `integer`

隨機種子，傳入相同 seed 可使生成結果盡量一致

**user** `string`

最終用戶識別，用於監控和限流

**n** `integer`

每個 prompt 生成的回覆候選數，預設為 1

**logit\_bias** `object`

詞元偏置，將 token ID 映射到偏置值（-100 到 100）

**tools** `array`

工具定義列表，每個工具須包含 `type` 和 `function`

**tool\_choice** `string`

工具選擇策略：`"auto"` / `"none"` / `"required"`，或指定工具名

## 基礎範例

**非串流請求**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "你是一個有用的助手"},
      {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ],
    "temperature": 0.7
  }'
```

**串流請求（SSE）**

```bash theme={null}
curl -N -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "doubao-seed-1-8-251228",
    "stream": true,
    "messages": [
      {"role": "system", "content": "你是一個有用的助手"},
      {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ]
  }'
```

**Python 範例**

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.mixroute.ai/v1"
)

# 非串流
completion = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "你是一個有用的助手"},
        {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ],
    temperature=0.7
)
print(completion.choices[0].message.content)

# 串流
stream = client.chat.completions.create(
    model="doubao-seed-1-8-251228",
    messages=[
        {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

## 進階功能

**工具呼叫**

支援 OpenAI 相容的工具呼叫格式：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "上海的天氣怎麼樣？"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "根據城市取得天氣資訊",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

**結構化輸出**

使用 JSON Schema 約束模型輸出格式：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.5",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "Answer",
        "schema": {
          "type": "object",
          "properties": {
            "summary": {"type": "string"}
          },
          "required": ["summary"]
        }
      }
    },
    "messages": [
      {"role": "user", "content": "回傳一個包含 summary 欄位的 JSON"}
    ]
  }'
```

**思考能力**

**DeepSeek**

DeepSeek 系列支援深度思考能力：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "請分析這道數學題：如果 x^2 + 2x - 3 = 0，求 x 的值"}
    ],
    "temperature": 0.6
  }'
```

回應將包含 `reasoning_content` 欄位展示思考過程。

**通義千問**

通義千問 Qwen 系列支援思考能力：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3.7-max",
    "messages": [
      {"role": "user", "content": "分析一下人工智慧的發展趨勢"}
    ],
    "enable_thinking": true
  }'
```

**GPT-5.6**

GPT-5.6 系列 (`gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`) 支援進階推理設定：

* `reasoning.mode` — 執行模式：`"standard"`（預設）或 `"pro"`。Pro Mode 執行更多推理工作，提升困難任務可靠性
* `reasoning.effort` — 推理強度：`none` / `low` / `medium` / `high` / `xhigh` / `max`（`max` 為新增檔位）

```shellscript theme={null}
curl https://api.mixroute.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk" \
  -d '{
    "model": "gpt-5.6-luna",
    "reasoning": {
      "mode": "pro",
	"effort":"max"
    },
    "input": "Analyze the potential risks of this database migration plan."
  }'
```

**Gemini**

Gemini 2.0 Flash Thinking 支援思考能力：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gemini-2.0-flash-thinking-exp",
    "messages": [
      {"role": "user", "content": "解釋量子計算的基本原理"}
    ]
  }'
```

**通義千問擴展**

通義千問支援額外的擴展參數：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3.7-max",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "enable_search": true,
    "search_options": {
      "search_strategy": "standard",
      "forced_search": false
    }
  }'
```

| 參數 | 說明 |
| - | - |
| `enable_search` | 啟用聯網搜尋 |
| `search_options.search_strategy` | 搜尋策略：`standard`/`pro` |
| `search_options.forced_search` | 強制搜尋 |

**聯網搜尋**

**Claude 搜尋**

Claude 模型支援聯網搜尋功能：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "今天有什麼重大新聞？"}
    ],
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5
      }
    ]
  }'
```

**Grok 搜尋**

Grok 模型支援即時聯網搜尋：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "grok-3",
    "messages": [
      {"role": "user", "content": "最新的科技新聞有哪些？"}
    ],
    "search_parameters": {
      "mode": "auto",
      "return_citations": true
    }
  }'
```

**GPT 檔案輸入**

GPT 模型支援直接處理檔案內容：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "請分析這個文件的內容"},
          {
            "type": "file",
            "file": {
              "url": "https://example.com/document.pdf"
            }
          }
        ]
      }
    ]
  }'
```

支援的檔案類型包括 PDF、Word、Excel、圖片等。

> [!TIP]
>
> 模型檔案處理能力有一定差別，請留意選擇支援上傳檔案類型的模型。

**Grok 推理**

Grok 模型支援增強推理能力：

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "grok-3-mini",
    "messages": [
      {"role": "user", "content": "分析以下邏輯問題：如果所有A都是B，且所有B都是C，那麼..."}
    ],
    "reasoning_effort": "high"
  }'
```

| reasoning\_effort | 說明 |
| - | - |
| `low` | 快速回應，基礎推理 |
| `medium` | 平衡模式 |
| `high` | 深度推理，更精確 |

## 回應格式

**非串流回應**

```json theme={null}
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "回覆內容..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}
```

**串流回應**

串流回應使用 Server-Sent Events (SSE) 格式：

```text theme={null}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"gpt-5.5","choices":[{"index":0,"delta":{"role":"assistant","content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"gpt-5.5","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"gpt-5.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

每個 chunk 包含增量內容，最後以 `[DONE]` 結束。

## 錯誤處理

| 異常類型 | 觸發情境 |
| - | - |
| AuthenticationError | API 金鑰無效或未授權 |
| NotFoundError | 模型不存在或不被支援 |
| APIConnectionError | 網路中斷或伺服器未回應 |
| RateLimitError | 請求頻率超限 |

```bash cURL theme={null}
curl --request POST \
  --url https://api.mixroute.ai/v1/chat/completions \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "你是一個有用的助手"},
      {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ],
    "temperature": 0.7
  }'
```

```python Python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.mixroute.ai/v1"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "你是一個有用的助手"},
        {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ],
    temperature=0.7
)
print(response.choices[0].message.content)
```

```javascript JavaScript theme={null}
const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: 'sk-xxxxxxxxxx',
  baseURL: 'https://api.mixroute.ai/v1'
});

const response = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    { role: 'system', content: '你是一個有用的助手' },
    { role: 'user', content: '請用中文簡要介紹人工智慧' }
  ],
  temperature: 0.7
});
console.log(response.choices[0].message.content);
```

```php PHP theme={null}
<?php
$client = new GuzzleHttp\Client();
$response = $client->post('https://api.mixroute.ai/v1/chat/completions', [
    'headers' => [
        'Authorization' => 'Bearer sk-xxxxxxxxxx',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'model' => 'gpt-5.5',
        'messages' => [
            ['role' => 'system', 'content' => '你是一個有用的助手'],
            ['role' => 'user', 'content' => '請用中文簡要介紹人工智慧']
        ],
        'temperature' => 0.7
    ]
]);
echo $response->getBody();
```

```go Go theme={null}
package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("sk-xxxxxxxxxx")
    config.BaseURL = "https://api.mixroute.ai/v1"
    client := openai.NewClientWithConfig(config)

    resp, _ := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "gpt-5.5",
            Messages: []openai.ChatCompletionMessage{
                {Role: "system", Content: "你是一個有用的助手"},
                {Role: "user", Content: "請用中文簡要介紹人工智慧"},
            },
        },
    )
    fmt.Println(resp.Choices[0].Message.Content)
}
```

```java Java theme={null}
import com.theokanning.openai.OpenAiService;
import com.theokanning.openai.completion.chat.*;

OpenAiService service = new OpenAiService("sk-xxxxxxxxxx");
ChatCompletionRequest request = ChatCompletionRequest.builder()
    .model("gpt-5.5")
    .messages(Arrays.asList(
        new ChatMessage("system", "你是一個有用的助手"),
        new ChatMessage("user", "請用中文簡要介紹人工智慧")
    ))
    .temperature(0.7)
    .build();
ChatCompletionResult result = service.createChatCompletion(request);
System.out.println(result.getChoices().get(0).getMessage().getContent());
```

```ruby Ruby theme={null}
require 'openai'

client = OpenAI::Client.new(
  access_token: 'sk-xxxxxxxxxx',
  uri_base: 'https://api.mixroute.ai/v1'
)

response = client.chat(
  parameters: {
    model: 'gpt-5.5',
    messages: [
      { role: 'system', content: '你是一個有用的助手' },
      { role: 'user', content: '請用中文簡要介紹人工智慧' }
    ],
    temperature: 0.7
  }
)
puts response.dig('choices', 0, 'message', 'content')
```

```json Response theme={null}
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "人工智慧是研究、開發用於模擬、延伸和擴展人的智慧的理論、方法、技術及應用系統的一門新的技術科學..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.