Chat API

无状态的紫微或奇门请求使用 OpenAI-compatible Chat Completions endpoint：

POST https://chat-api.iztro.com/v2/chat/completions
Authorization: Bearer $ZIWEI_API_KEY
Content-Type: application/json

完整请求

curl https://chat-api.iztro.com/v2/chat/completions \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "iztro-qimen-v3",
    "reasoning_effort": "high",
    "max_tokens": 384000,
    "language": "zh",
    "messages": [
      {
        "role": "user",
        "content": "我们已经谈过两次合作，但关键条款仍未确定。现在应该推进、继续谈判，还是暂缓？如果可以推进，请给出最近的行动窗口。"
      }
    ],
    "metadata": {
      "current_datetime": "2026-07-20T14:30:00+08:00"
    }
  }'

紫微使用 iztro-ziwei-v3 或 iztro-ziwei-v3-fast；奇门使用 iztro-qimen-v3 或 iztro-qimen-v3-fast。四个模型都可以通过 messages 接收对话历史。

请求字段

字段	是否必填	说明
model	是	iztro-ziwei-v3、iztro-qimen-v3、iztro-ziwei-v3-fast 或 iztro-qimen-v3-fast
messages	是	OpenAI-compatible 会话消息
reasoning_effort	否	省略时，标准模型默认开启思考，fast 模型默认关闭。显式 none、minimal 或 low 关闭思考；medium、high、xhigh 或 max 开启思考，强度统一为 high。
language	否	回复语言：zh、en、ko、ja 或 vi。省略时自动跟随当前对话语言。
stream	否	设为 true 后通过 SSE 流式返回 token
max_tokens	否	可选输出上限；省略时使用当前配置的 384,000 个输出 token 最大值
temperature	否	仅非思考模式使用的采样温度，范围 0 到 2；不能和 top_p 同时设置
top_p	否	仅非思考模式使用的核采样值，范围 0 到 1；不能和 temperature 同时设置
frequency_penalty	不支持	DeepSeek 已不再支持；包含该字段的请求会被拒绝
presence_penalty	不支持	DeepSeek 已不再支持；包含该字段的请求会被拒绝
tools	否	OpenAI-compatible 开发者函数定义
tool_choice	否	控制开发者提供的工具，不选择隐藏的 Iztro 计算
parallel_tool_calls	否	允许一轮调用多个开发者工具
enable_iztro_call	否	默认为 true；设为 false 后禁用托管紫微或奇门计算
metadata.current_datetime	奇门建议提供	用户当地的 ISO 8601 问事时刻，必须包含 UTC 偏移量
metadata.system_prompt_override	否	应用自定义指令，最多 8,000 字符

这里使用的就是 OpenAI-compatible Chat Completions 标准字段 reasoning_effort。不要发送自定义 thinking 字段或 Iztro 自定义值 deep。推理强度不控制回答长度；回答上限请单独使用 max_tokens。

人生报告与多轮咨询的提示词见场景与模型。

采样只在非思考路径可用。temperature 和 top_p 只能设置其中一个。思考请求如果包含任一采样字段会被拒绝，因为 DeepSeek 原本会直接忽略这些设置。

以上字段构成完整的托管模型请求契约。Python、TypeScript 对应字段名、默认行为，以及上游 Agents SDK 中当前未被 Iztro 使用的字段，详见模型设置。

指定 language 后，所有面向用户的正文和翻译后的术数术语都只使用该语言。代码、URL、模型名、工具/事件标识和 JSON 键保持原样。

响应

响应遵循 Chat Completions 结构。答案位于 choices[0].message.content，usage 提供 token 用量；额外的 iztro_tools 数组用于说明托管模型调用了哪些公开 Iztro 计算。

流式请求的每个 SSE 事件使用 Chat Completions chunk 结构。相关回答文本生成前，工具活动会先通过 iztro_tools 返回。

iztro_tools 使用以下公开计算名称：

模型系列	计算名称
紫微	iztro-mingpan、iztro-daxian、iztro-xiaoxian、iztro-liunian、iztro-liuyue、iztro-liuri
奇门	qimen-qigua、qimen-yingqi

对应 fast 模型使用相同名称。返回值可能附带查询范围，例如 iztro-liunian 2026-2030。SDK 工具事件也使用这些名称，用法见流式输出。

需要持久化服务端会话时，请使用 Session API 或 SDK ChatSession。