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

# OpenAI 兼容的 Chat Completions

> OpenAI Chat Completions API 的即插即用替代方案。將 OpenAI SDK 指向 Theo,無需改動現有代碼即可繼續使用。

Theo 在 `POST /api/v1/chat/completions` 上實現了 OpenAI Chat Completions 通信協議。任何使用 OpenAI SDK 的應用都可以將 `baseURL` 指向 `https://www.hitheo.ai/api/v1`,換上 Theo API 密鑰即可正常運行——該端點接受相同的 `{ model, messages, stream, temperature, ... }` 結構,並返回相同的 `chat.completion` / `chat.completion.chunk` 對象。

<Note>
  **響應結構**與 OpenAI 完全一致。底層的**路由**則由 Theo 負責——意圖分類、模型選擇與自動故障轉移。傳入 `model: "theo-1-auto"` 可讓 Theo 為每個請求選擇最合適的引擎。
</Note>

## 基礎 URL

請使用規範的 `www` 主機名。OpenAI SDK 會在其後追加 `/chat/completions`,因此該基礎 URL 最終會解析到真實的 `POST /api/v1/chat/completions` 路由:

```
https://www.hitheo.ai/api/v1
```

<Warning>
  務必使用 `www` 主機名。裸域名 `https://hitheo.ai` 會以 307 重定向到 `www`,而大多數 HTTP 客戶端在跨重定向時會剝離 `Authorization` 頭——請求會以未認證狀態到達,並返回 `401`。
</Warning>

## 身份驗證

使用標準的 Bearer 令牌請求頭。你的 Theo API 密鑰將替代原來的 OpenAI 密鑰。

```bash theme={null}
Authorization: Bearer theo_sk_...
```

## 即插即用示例(OpenAI SDK)

<CodeGroup>
  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  const theo = new OpenAI({
    apiKey: process.env.THEO_API_KEY,
    baseURL: "https://www.hitheo.ai/api/v1",
  });

  const res = await theo.chat.completions.create({
    model: "theo-1-auto",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "Write me a haiku about Miami." },
    ],
  });

  console.log(res.choices[0].message.content);
  ```

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

  theo = OpenAI(
      api_key=os.environ["THEO_API_KEY"],
      base_url="https://www.hitheo.ai/api/v1",
  )

  res = theo.chat.completions.create(
      model="theo-1-auto",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Write me a haiku about Miami."},
      ],
  )

  print(res.choices[0].message.content)
  ```

  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "theo-1-auto",
      "messages": [
        { "role": "user", "content": "Write me a haiku about Miami." }
      ]
    }'
  ```
</CodeGroup>

## 流式響應

將 `stream` 設為 `true`,即可接收以 `data: [DONE]` 結尾的 `chat.completion.chunk` 對象 SSE 流,行為與 OpenAI 完全一致。

```typescript theme={null}
const stream = await theo.chat.completions.create({
  model: "theo-1-auto",
  messages: [{ role: "user", content: "Stream me a short poem." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

## 支持的 `model` 取值

傳入任意 Theo 品牌模型 ID。推薦使用 `theo-1-auto`,讓 Theo 的意圖分類器為每個請求挑選最合適的引擎;如果你想固定路由,也可以傳入具體的引擎。

| 模型 ID | Theo 模式 | 最適用場景 |
| - | - | - |
| `theo-1-auto` | auto | 讓 Theo 為每條提示選擇合適的引擎 |
| `theo-1-flash` | fast | 快速響應、簡短對話、分類任務 |
| `theo-1-reason` | think | 深度推理、分析、規劃 |
| `theo-1-code` | code | 代碼生成與審查 |
| `theo-1-create` | image | 圖像生成 |
| `theo-1-motion` | video | 視頻生成 |
| `theo-1-research` | research | 帶引用的多步網絡研究 |
| `theo-1-roast` | roast | 不加過濾的幽默與犀利吐槽 |
| `theo-1-genui` | genui | 生成式 UI 組件 |
| `theo-1-analyze` | domain\_analysis | 面向業務運營、財務與合規的領域分析 |
| `theo-1-extract` | data\_extraction | OCR 與結構化數據提取 |
| `theo-1-vision` | vision | 多模態圖像分析 |

未知的模型字符串會回退到 `auto`,Theo 會像處理其他任何提示一樣為該請求路由。

## 請求體

請求體沿用標準的 OpenAI Chat Completion 結構。下方未列出的字段仍會被接受,但會被忽略(例如 `top_p`、`n`、`max_tokens`、`user`)。

<ParamField body="model" type="string" default="theo-1-auto">
  一個 Theo 模型 ID。有效取值參見上方表格。
</ParamField>

<ParamField body="messages" type="object[]" required>
  到目前為止的對話內容。每條消息包含 `{ role, content }`。支持的角色有:`system`、`user`、`assistant`。`tool` 消息會被接受但忽略(工具調用狀態由 Theo 內部管理)。

  **最後一條 user 消息**會被視為提示。所有 `system` 消息會被合併為單一的系統提示,覆蓋 Theo 的默認角色設定。此前的 user/assistant 輪次會作為對話上下文注入。
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  當設為 `true` 時,返回以 `data: [DONE]` 結尾的 `chat.completion.chunk` 對象 SSE 流。
</ParamField>

<ParamField body="temperature" type="number">
  採樣温度(0–2)。
</ParamField>

<ParamField body="conversation_id" type="string">
  **Theo 專屬參數。** 將此次補全關聯到一個已有的 Theo 對話,使其記憶能夠跨渠道持續保留。省略此參數則發送無狀態請求。
</ParamField>

<ParamField body="skills" type="string[]">
  **Theo 專屬參數。** 按 slug 為本次請求激活技能。會與用戶已安裝的技能合併。
</ParamField>

<ParamField body="metadata" type="object">
  **Theo 專屬參數。** 附加到審計日誌中的任意鍵值數據。
</ParamField>

## 響應

標準的 OpenAI `chat.completion`(流式時為 `chat.completion.chunk`)。Theo 專屬的元數據會以 `theo_metadata` 擴展字段返回,以避免與現有 OpenAI 客戶端的預期結構衝突。

```json theme={null}
{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "created": 1715872800,
  "model": "theo-1-flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Neon waves on sand..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 38,
    "total_tokens": 62
  },
  "theo_metadata": {
    "mode": "auto",
    "resolved_mode": "fast",
    "tools_used": [],
    "artifacts": [],
    "engine": "theo-core"
  }
}
```

## 何時改用 `/v1/completions`

* 你需要的是**單輪提示**字符串,而不是消息數組。
* 你想要更豐富的**原生 Theo 響應**(後續追問、產物、工具調用軌跡),而不是 OpenAI 的結構。
* 你想在每次請求中單獨控制 `persona` 或 `response_style`。

原生端點參見 [創建補全](/api-reference/completions/create)。

## 同樣適用按密鑰編排

該端點運行的是與原生端點**完全相同的按密鑰編排**:無論你為該 API 密鑰配置了什麼——[編排器圖譜](/dashboard/orchestrator)、模型鎖定、[網關護欄](/guides/guardrails)、[路由工作室](/core-concepts/model-routing)偏好設置、模型允許列表,以及[上下文窗口保護](/api-reference/completions/openai-compat#errors)——都會同樣作用於此處的請求。因此,無論你是通過 OpenAI SDK 還是原生 API 調用,一個你在控制台或通過 [MCP 工具](/mcp/tools)配置好的密鑰都會表現一致。護欄可以拒絕請求(`422`),超出該密鑰允許列表的模型會被拒絕(`403`),超出體積的請求會返回 `400 context_length_exceeded`。沒有此類配置的密鑰不受影響——它們仍會按 Theo 的默認設置路由,與以往一致。

## 錯誤

返回與其他所有 v1 端點相同的錯誤信封:

```json theme={null}
{
  "error": {
    "message": "Validation failed: messages must contain at least one message.",
    "type": "invalid_request_error",
    "code": "validation_error"
  }
}
```

| 狀態碼 | 錯誤碼 | 描述 |
| - | - | - |
| 400 | `validation_error` | `messages` 缺失、為空或格式錯誤 |
| 400 | `empty_prompt` | `messages` 中只包含 system/tool 消息 |
| 400 | `context_length_exceeded` | 請求體量超出該密鑰所有模型能容納的上限——請在編排器中添加上下文更大的模型,或縮短請求內容 |
| 401 | `invalid_api_key` | `Authorization: Bearer theo_sk_...` 缺失或無效 |
| 402 | `insufficient_credits` | 賬戶餘額不足以完成預扣（pre-flight reservation） |
| 403 | `model_not_allowed` | 請求解析到的模型不在該密鑰的模型允許列表中 |
| 422 | `guardrail_violation` | 該密鑰上的網關護欄策略拒絕了此請求 |
| 422 | `orchestrator_no_path` | 該密鑰的編排器圖譜未能為此請求解析出有效路徑 |
| 404 | `not_found` | 未找到 `conversation_id` |
| 429 | `rate_limit_exceeded` | 請查看 `Retry-After` |
| 500 | `server_error` | 內部錯誤 |


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