> ## 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.