Skip to main content
POST
创建补全
Theo API 的核心端点。让提示词经过完整的编排流水线,并返回完整的响应。
如需实时令牌传输,请设置 stream: true,或参阅 流式补全。

认证

需要 Bearer 令牌。参阅 认证。

请求体

string
必填
提示词文本。必须为非空字符串。
string
默认值:"auto"
执行模式。设置为 auto 时,Theo 会对提示词进行分类并自动选择最优引擎。可用模式:
  • auto — 对提示词分类并路由到最佳引擎(默认)
  • fast — 面向简单查询的低延迟响应
  • think — 面向复杂分析的深度推理
  • code — 代码生成(Theo Code 引擎,扩展输出预算)
  • image — 图像生成(Theo Create)
  • video — 异步。 请使用 POST /api/v1/video 并轮询任务状态,而不是本端点。
  • research — 异步。 请使用 POST /api/v1/research 并轮询任务状态,而不是本端点。
  • roast — 幽默、不拘一格的语气
  • genui — 生成交互式 UI 组件(OpenUI Lang)
research 和 video 是异步的,不得发送给 /completions(或 stream())。它们以后台任务形式运行;在此处调用会导致工作被内联执行,请求会在完成前触发超时。请通过 POST /api/v1/research / POST /api/v1/video 将其加入队列,并使用 获取任务状态 进行轮询。@hitheo/sdk 在你把这些模式传给 complete() / stream() 时会立即抛出 TheoUsageError。参阅 异步任务指南。
boolean
默认值:"false"
启用 SSE 流式传输。为 true 时,返回 text/event-stream 响应而非 JSON。参阅 流式传输。
string
延续一段已有的对话。传入对话 ID 以保持多轮上下文。
string[]
本次请求要激活的技能 slug。这些技能会与用户已安装的技能合并。每个 slug 会为本次补全激活相应技能的提示扩展、工具和模型偏好。你可以在控制台(每张技能卡片上的复制图标)、GET /api/v1/skills,或技能构建器的 Input 节点中找到 slug。完整指南参阅 通过 API 激活技能。
object[]
代理循环期间模型可调用的内联工具定义。
string | object
默认值:"theo"
为本次请求覆盖 Theo 的人格设定。
  • "theo" — 默认的 Theo 角色
  • "none" — 不使用角色(原始模型输出)
  • { "system_prompt": "You are..." } — 自定义系统提示词
number
采样温度(0–2)。数值越高,输出越具创造性。
integer
默认值:"8"
代理循环的最大迭代次数(1–20)。每次迭代为一个「思考 → 行动 → 观察」循环。
object
为特定模式覆盖所用引擎。键为模式名称(例如 "code"、"think"),值为 Theo 引擎 ID(例如 "theo-1-reason"、"theo-1-flash")。有效引擎 ID 参阅 列出模型。
string
默认值:"theo"
响应格式。"theo" 为默认格式,"openai" 为兼容 OpenAI 的格式。
object
附加在此次补全上的任意键值元数据。会在响应中原样返回,并记录在审计日志中。
string
GenUI 模式下的组件库标识符。供 E.V.I. 调用方用于自定义 UI 渲染。
boolean
默认值:"true"
设为 false 可跳过本次请求的长期记忆检索与注入。适用于无状态 / 对隐私敏感的调用场景,即不希望历史记忆影响本次回答。
object
面向无状态调用方的内联对话信封 — 当未提供 conversation_id 时,服务器会使用其中最近的 messages(最多 20 条),使「再写长一点」这类追问能够正确解析上下文。
object
按请求覆盖的响应风格配置(格式、精确度、意图),叠加在该密钥的默认设置之上。
object
按请求覆盖的人格 / 特质配置叠加层。
boolean
默认值:"true"
品牌总开关。设为 false 会从系统提示词中剥离 Theo 的角色 / 品牌信息(对 persona 的超集控制)。
boolean
设为 true 时,会将响应限定在该密钥的品牌目录(Brand Soul)范围内 — 只推荐你自己的产品/内容,并将偏离主题的请求引导回来。
object[]
用于视觉轮次的图片附件。每项为 { type: "image_url", url } 或 { type: "image_base64", data, mime_type }(PNG / JPEG / WebP / GIF,base64 编码后 ≤ 15MB)。
string
为 image 模式固定图像子引擎(否则自动选择)。
string
为 image 模式固定图像质量档位。
string
隐身媒体模型固定(stealth_image / stealth_video)。
string
隐身媒体的宽高比。
string
隐身视频片段的时长。

请求示例

结合技能与工具

响应

string
唯一的补全 ID(前缀为 cmpl_)。
string
固定为 "completion"。
string
ISO 8601 时间戳。
string
生成的文本内容。
string
你请求时指定的模式(例如 "auto")。
string
Theo 在意图分类后实际使用的模式(例如 "fast"、"think"、"code")。
object
处理该请求的 Theo 引擎。
object[]
代理循环期间调用过的工具。
object[]
在本次补全过程中生成的文件(图片、代码、文档)。
object[]
建议的后续提示词。
object
令牌计数与费用。
对于非文本模式(image、video、tts、stt),prompt_tokens 和 completion_tokens 始终为 0 — 令牌在这些场景下不是有意义的计费单位。请以 usage.cost_cents 作为这些模式下唯一的用量指标。
object | null
你在请求中传入的元数据,原样回传。
string | null
本轮对话最终解析所依据的服务端会话 ID。若未创建或关联任何会话,则为 null。若请求中传入了 conversation_id,则原样回传。
string
服务器分配的请求标识符(同时以 X-Request-Id 响应头返回)。在提交支持工单时附上此值,便于我们在日志中查询该请求。

响应示例

兼容 OpenAI 的格式

传入 format: "openai" 即可获得符合 OpenAI chat.completions 格式的响应。这使其可以直接替换现有基于 OpenAI 的应用。
该响应遵循 OpenAI 的 chat.completion 结构,包含 choices、usage 和 model 字段。

语义缓存

非会话类补全(未提供 conversation_id)会被自动缓存。相同的请求会零成本即时返回缓存结果。参阅 语义缓存。 缓存命中的响应体中会包含 "_cached": true。

错误