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

# 创建补全

> 让提示词经过完整的编排流水线 — 意图分类、技能加载、模型路由、代理循环与响应生成。

Theo API 的核心端点。让提示词经过完整的编排流水线，并返回完整的响应。

<Note>
  如需实时令牌传输，请设置 `stream: true`，或参阅 [流式补全](/api-reference/completions/streaming)。
</Note>

## 认证

需要 Bearer 令牌。参阅 [认证](/api-reference/authentication)。

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

## 请求体

<ParamField body="prompt" type="string" required>
  提示词文本。必须为非空字符串。
</ParamField>

<ParamField body="mode" type="string" default="auto">
  执行模式。设置为 `auto` 时，Theo 会对提示词进行分类并自动选择最优引擎。

  可用模式：

  * `auto` — 对提示词分类并路由到最佳引擎（默认）
  * `fast` — 面向简单查询的低延迟响应
  * `think` — 面向复杂分析的深度推理
  * `code` — 代码生成（Theo Code 引擎，扩展输出预算）
  * `image` — 图像生成（Theo Create）
  * `video` — **异步。** 请使用 [`POST /api/v1/video`](/api-reference/video/generate) 并轮询任务状态，而不是本端点。
  * `research` — **异步。** 请使用 [`POST /api/v1/research`](/api-reference/research/create) 并轮询任务状态，而不是本端点。
  * `roast` — 幽默、不拘一格的语气
  * `genui` — 生成交互式 UI 组件（OpenUI Lang）
</ParamField>

<Warning>
  `research` 和 `video` 是**异步的**，不得发送给 `/completions`（或 `stream()`）。它们以后台任务形式运行；在此处调用会导致工作被内联执行，请求会在完成前触发超时。请通过 [`POST /api/v1/research`](/api-reference/research/create) / [`POST /api/v1/video`](/api-reference/video/generate) 将其加入队列，并使用 [获取任务状态](/api-reference/jobs/get) 进行轮询。`@hitheo/sdk` 在你把这些模式传给 `complete()` / `stream()` 时会立即抛出 `TheoUsageError`。参阅 [异步任务指南](/guides/async-jobs)。
</Warning>

<ParamField body="stream" type="boolean" default="false">
  启用 SSE 流式传输。为 `true` 时，返回 `text/event-stream` 响应而非 JSON。参阅 [流式传输](/api-reference/completions/streaming)。
</ParamField>

<ParamField body="conversation_id" type="string">
  延续一段已有的对话。传入对话 ID 以保持多轮上下文。
</ParamField>

<ParamField body="skills" type="string[]">
  本次请求要激活的技能 slug。这些技能会与用户已安装的技能合并。

  每个 slug 会为本次补全激活相应技能的提示扩展、工具和模型偏好。你可以在控制台（每张技能卡片上的复制图标）、`GET /api/v1/skills`，或技能构建器的 Input 节点中找到 slug。

  完整指南参阅 [通过 API 激活技能](/guides/skills-api)。
</ParamField>

<ParamField body="tools" type="object[]">
  代理循环期间模型可调用的内联工具定义。

  <Expandable title="Tool object">
    <ParamField body="name" type="string" required>
      工具名称（例如 `check_inventory`）。
    </ParamField>

    <ParamField body="description" type="string" required>
      工具的作用 — 模型会据此判断何时调用它。
    </ParamField>

    <ParamField body="input_schema" type="object">
      描述工具输入参数的 JSON Schema。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="persona" type="string | object" default="theo">
  为本次请求覆盖 Theo 的人格设定。

  * `"theo"` — 默认的 Theo 角色
  * `"none"` — 不使用角色（原始模型输出）
  * `{ "system_prompt": "You are..." }` — 自定义系统提示词
</ParamField>

<ParamField body="temperature" type="number">
  采样温度（0–2）。数值越高，输出越具创造性。
</ParamField>

<ParamField body="max_iterations" type="integer" default="8">
  代理循环的最大迭代次数（1–20）。每次迭代为一个「思考 → 行动 → 观察」循环。
</ParamField>

<ParamField body="model_overrides" type="object">
  为特定模式覆盖所用引擎。键为模式名称（例如 `"code"`、`"think"`），值为 Theo 引擎 ID（例如 `"theo-1-reason"`、`"theo-1-flash"`）。有效引擎 ID 参阅 [列出模型](/api-reference/models/list)。
</ParamField>

<ParamField body="format" type="string" default="theo">
  响应格式。`"theo"` 为默认格式，`"openai"` 为兼容 OpenAI 的格式。
</ParamField>

<ParamField body="metadata" type="object">
  附加在此次补全上的任意键值元数据。会在响应中原样返回，并记录在审计日志中。
</ParamField>

<ParamField body="component_library" type="string">
  GenUI 模式下的组件库标识符。供 E.V.I. 调用方用于自定义 UI 渲染。
</ParamField>

<ParamField body="memory" type="boolean" default="true">
  设为 `false` 可跳过本次请求的长期记忆检索与注入。适用于无状态 / 对隐私敏感的调用场景，即不希望历史记忆影响本次回答。
</ParamField>

<ParamField body="conversation" type="object">
  面向无状态调用方的内联对话信封 — 当未提供 `conversation_id` 时，服务器会使用其中最近的 `messages`（最多 20 条），使「再写长一点」这类追问能够正确解析上下文。
</ParamField>

<ParamField body="response_style" type="object">
  按请求覆盖的响应风格配置（格式、精确度、意图），叠加在该密钥的默认设置之上。
</ParamField>

<ParamField body="personality_config" type="object">
  按请求覆盖的人格 / 特质配置叠加层。
</ParamField>

<ParamField body="theo_branding" type="boolean" default="true">
  品牌总开关。设为 `false` 会从系统提示词中剥离 Theo 的角色 / 品牌信息（对 `persona` 的超集控制）。
</ParamField>

<ParamField body="brand_soul" type="boolean">
  设为 `true` 时，会将响应限定在该密钥的品牌目录（Brand Soul）范围内 — 只推荐你自己的产品/内容，并将偏离主题的请求引导回来。
</ParamField>

<ParamField body="attachments" type="object[]">
  用于视觉轮次的图片附件。每项为 `{ type: "image_url", url }` 或 `{ type: "image_base64", data, mime_type }`（PNG / JPEG / WebP / GIF，base64 编码后 ≤ 15MB）。
</ParamField>

<ParamField body="image_model" type="string">
  为 `image` 模式固定图像子引擎（否则自动选择）。
</ParamField>

<ParamField body="image_quality" type="string">
  为 `image` 模式固定图像质量档位。
</ParamField>

<ParamField body="stealth_model" type="string">
  隐身媒体模型固定（`stealth_image` / `stealth_video`）。
</ParamField>

<ParamField body="stealth_aspect" type="string">
  隐身媒体的宽高比。
</ParamField>

<ParamField body="stealth_duration" type="string">
  隐身视频片段的时长。
</ParamField>

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/completions \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Explain microservices architecture",
      "mode": "auto",
      "temperature": 0.7
    }'
  ```

  ```typescript SDK theme={null}
  import { Theo } from "@hitheo/sdk";

  const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

  const res = await theo.complete({
    prompt: "Explain microservices architecture",
    mode: "auto",
    temperature: 0.7,
  });

  console.log(res.content);
  console.log(res.model.label);     // e.g. "Theo Flash"
  console.log(res.usage.cost_cents); // e.g. 0.02
  ```
</CodeGroup>

### 结合技能与工具

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/completions \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Check current inventory levels for SKU-1234",
      "mode": "auto",
      "skills": ["inventory-check"],
      "tools": [
        {
          "name": "check_stock",
          "description": "Look up current stock levels by SKU",
          "input_schema": {
            "type": "object",
            "properties": {
              "sku": { "type": "string" },
              "warehouse": { "type": "string" }
            },
            "required": ["sku"]
          }
        }
      ],
      "persona": { "system_prompt": "You are Atlas, an operations assistant." },
      "max_iterations": 5
    }'
  ```

  ```typescript SDK theme={null}
  const res = await theo.complete({
    prompt: "Check current inventory levels for SKU-1234",
    skills: ["inventory-check"],
    tools: [
      {
        name: "check_stock",
        description: "Look up current stock levels by SKU",
        input_schema: {
          type: "object",
          properties: {
            sku: { type: "string" },
            warehouse: { type: "string" },
          },
          required: ["sku"],
        },
      },
    ],
    persona: { system_prompt: "You are Atlas, an operations assistant." },
    max_iterations: 5,
  });
  ```
</CodeGroup>

## 响应

<ResponseField name="id" type="string">
  唯一的补全 ID（前缀为 `cmpl_`）。
</ResponseField>

<ResponseField name="object" type="string">
  固定为 `"completion"`。
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 时间戳。
</ResponseField>

<ResponseField name="content" type="string">
  生成的文本内容。
</ResponseField>

<ResponseField name="mode" type="string">
  你请求时指定的模式（例如 `"auto"`）。
</ResponseField>

<ResponseField name="resolved_mode" type="string">
  Theo 在意图分类后实际使用的模式（例如 `"fast"`、`"think"`、`"code"`）。
</ResponseField>

<ResponseField name="model" type="object">
  处理该请求的 Theo 引擎。

  <Expandable title="Model object">
    <ResponseField name="id" type="string">
      Theo 品牌化的模型 ID（例如 `"theo-1-flash"`、`"theo-1-reason"`）。
    </ResponseField>

    <ResponseField name="label" type="string">
      人类可读的名称（例如 `"Theo Flash"`、`"Theo Reason"`）。
    </ResponseField>

    <ResponseField name="engine" type="string">
      引擎子系统（例如 `"theo-core"`、`"theo-vision"`）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tools_used" type="object[]">
  代理循环期间调用过的工具。

  <Expandable title="Tool usage object">
    <ResponseField name="name" type="string">工具名称。</ResponseField>
    <ResponseField name="status" type="string">`"success"` 或 `"error"`。</ResponseField>
    <ResponseField name="description" type="string">工具描述。</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="artifacts" type="object[]">
  在本次补全过程中生成的文件（图片、代码、文档）。
</ResponseField>

<ResponseField name="follow_ups" type="object[]">
  建议的后续提示词。

  <Expandable title="Follow-up object">
    <ResponseField name="label" type="string">建议项的简短标签。</ResponseField>
    <ResponseField name="prompt" type="string">完整的提示词文本。</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  令牌计数与费用。

  <Expandable title="Usage object">
    <ResponseField name="cost_cents" type="number">费用（单位：美分）。</ResponseField>
    <ResponseField name="prompt_tokens" type="integer">消耗的输入令牌数。对于非文本模式（`image`、`video`、`tts`、`stt`）始终为 `0`。</ResponseField>
    <ResponseField name="completion_tokens" type="integer">生成的输出令牌数。对于非文本模式始终为 `0`。</ResponseField>
    <ResponseField name="total_tokens" type="integer">令牌总数。</ResponseField>
    <ResponseField name="cached" type="boolean">当响应来自语义缓存时，该字段存在且为 `true`。</ResponseField>
  </Expandable>
</ResponseField>

<Note>
  对于非文本模式（`image`、`video`、`tts`、`stt`），`prompt_tokens` 和 `completion_tokens` 始终为 `0` — 令牌在这些场景下不是有意义的计费单位。请以 `usage.cost_cents` 作为这些模式下唯一的用量指标。
</Note>

<ResponseField name="metadata" type="object | null">
  你在请求中传入的元数据，原样回传。
</ResponseField>

<ResponseField name="conversation_id" type="string | null">
  本轮对话最终解析所依据的服务端会话 ID。若未创建或关联任何会话，则为 `null`。若请求中传入了 `conversation_id`，则原样回传。
</ResponseField>

<ResponseField name="request_id" type="string">
  服务器分配的请求标识符（同时以 `X-Request-Id` 响应头返回）。在提交支持工单时附上此值，便于我们在日志中查询该请求。
</ResponseField>

### 响应示例

```json theme={null}
{
  "id": "cmpl_abc123",
  "object": "completion",
  "created": "2026-04-10T12:00:00Z",
  "content": "Microservices architecture is a design pattern where an application is composed of small, independent services...",
  "mode": "auto",
  "resolved_mode": "fast",
  "model": {
    "id": "theo-1-flash",
    "label": "Theo Flash",
    "engine": "theo-core"
  },
  "tools_used": [],
  "artifacts": [],
  "follow_ups": [
    { "label": "Compare with monoliths", "prompt": "Compare microservices vs monolithic architecture" },
    { "label": "Service mesh", "prompt": "Explain service mesh in microservices" }
  ],
  "usage": {
    "cost_cents": 0.02,
    "prompt_tokens": 12,
    "completion_tokens": 156,
    "total_tokens": 168
  },
  "metadata": null,
  "conversation_id": null,
  "request_id": "req_9f2e1a"
}
```

## 兼容 OpenAI 的格式

传入 `format: "openai"` 即可获得符合 OpenAI `chat.completions` 格式的响应。这使其可以直接替换现有基于 OpenAI 的应用。

```bash theme={null}
curl -X POST https://www.hitheo.ai/api/v1/completions \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello",
    "format": "openai"
  }'
```

该响应遵循 OpenAI 的 `chat.completion` 结构，包含 `choices`、`usage` 和 `model` 字段。

## 语义缓存

非会话类补全（未提供 `conversation_id`）会被自动缓存。相同的请求会**零成本**即时返回缓存结果。参阅 [语义缓存](/guides/semantic-caching)。

缓存命中的响应体中会包含 `"_cached": true`。

## 错误

| 状态码 | 错误码 | 说明 |
| - | - | - |
| 400 | `validation_error` | 请求体无效（缺少 prompt、mode 非法等） |
| 400 | `context_length_exceeded` | 请求超出该密钥上最大的上下文窗口 — 请添加支持更大上下文的模型或缩短请求内容 |
| 401 | `invalid_api_key` | API 密钥缺失或无效 |
| 402 | `insufficient_credits` | 账户余额不足 |
| 403 | `model_not_allowed` | 请求解析到的模型不在该密钥的模型允许列表中 |
| 404 | `not_found` | 未找到该对话 ID |
| 422 | `guardrail_violation` | 该密钥上的某条 Gateway Guardrails 策略拒绝了该请求 |
| 422 | `orchestrator_no_path` | 该密钥的编排器图未能为此请求解析出可用路径 |
| 429 | `rate_limit_exceeded` | 请求过于频繁 — 请查看 `Retry-After` 响应头 |
| 500 | `server_error` | 服务器内部错误 |


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