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