请求参数
跨能力索引：通用 HTTP 头、model 等入口字段，以及各能力全量参数去哪查——不替代各端点字段表。
| 我想… | 去这里 |
|---|---|
| 跑通最小请求 | 快速入门 · API 概述 |
| 流式 | 流式输出 |
| 幂等头 | 幂等与结算 |
| 打开控制台 | 控制台 · API 密钥 ↗ |
| 想查什么 | 去哪 |
|---|---|
| 某能力全部字段 | API · 高级参数（如 对话补全、生图、生视频） |
| 多模态 | 多模态入门 |
下文从通用请求头与 model 入口展开。
HTTP 请求头（通用）
适用于 POST /v1/chat/completions（生文、生图、流式）及多数 JSON API。生视频创建任务以 创建视频生成任务 为准。
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer xh-...（见 管理 API 密钥） |
Content-Type | 是 | application/json |
Accept | 流式时建议 | 流式生文：text/event-stream |
X-Request-Id | 否 | 追踪 ID，排障关联；最长 128 字符 |
X-Idempotency-Key | 否 | 结算幂等键；同 workspace 内相同键仅首笔成功扣费；重试须不变 |
X-Conversation-Id | 否 | 会话分组；多轮 Agent / Prompt Cache 建议固定传同一值；最长 128 字符 |
X-Session-Id | 否 | X-Conversation-Id 别名；仅当未传后者时生效 |
成功或失败响应（含 SSE）通常回写 X-Request-Id、X-Settlement-Key；传入 X-Conversation-Id 时会回写该头。
Prompt Cache（生文）
部分生文模型支持 Prompt Cache：对多轮对话中重复的前缀 prompt 降低 input 成本。网关自动维护会话上下文，无需在请求体中传额外缓存控制字段。
- 提升命中率：同一 Agent / Chat 任务内固定
X-Conversation-Id（或X-Session-Id）。 - 命中量、流式
usage与计费见 对话补全 · 高级参数 · Prompt Cache。
计费
不传 X-Idempotency-Key 时，每次 HTTP 调用独立计费。网络超时后重放同一笔业务：保持结算键不变，追踪 ID 可换可不变。
详见 API 概述 · 追踪与结算。
请求体：model 与能力入口
| 字段 | 必填 | 说明 |
|---|---|---|
model | 是 | 模型 ID；通过 获取模型 或 模型广场 获取；勿使用列表中不存在的 ID |
发现可用模型：GET /models，可选 modality=text|image|video|all。勿依赖 output_modalities 等第三方专属查询参数。字段见 获取模型 · 高级参数。
生文 · 常用 body 字段（摘要）
完整表见 高级参数 · 生文。
| 字段 | 类型 | 说明 |
|---|---|---|
messages | array | 必填。role + content（string 或 Part 数组） |
stream | boolean | 默认 false；true 时见 流式输出（SSE） |
stream_options | object | 仅 stream=true；如 include_usage |
temperature | number | 采样随机性，常用 0~2 |
top_p | number | nucleus 采样，常用 0~1 |
max_tokens | integer | 与 max_completion_tokens 互斥 |
max_completion_tokens | integer | 含思维链时的输出上限 |
thinking_enabled / reasoning_effort | boolean / string | 深度思考；按模型能力 |
stop | string | string[] | 停止词 |
response_format | object | string | 结构化输出 |
tools / tool_choice / parallel_tool_calls | — | 工具调用 |
modalities | array | 纯生文建议省略或 ["text"] |
多模态 输入（image_url、file 等 Part）见 图片输入、视频输入。
生图 · 两条路径
| 路径 | 形态 | 文档 |
|---|---|---|
POST /v1/images/generations | OpenAI Images 文生图（prompt / size / n） | 创建图像（Images） |
POST /v1/images/edits | OpenAI Images 改图（multipart） | 编辑图像（Images） |
POST /v1/chat/completions | 统一契约：modalities + image_config | 创建图像生成（chat） |
统一契约额外字段：
| 字段 | 说明 |
|---|---|
modalities | 须含 image（常配合 text） |
image_config | 画幅、分辨率、参考图等 |
| 勿用 | 原因 |
|---|---|
stream: true | 生图不支持流式 |
trinity_async.* | 生图不支持，传入报 invalid_request |
生视频 · 独立端点参数
| 步骤 | 方法 | 路径 | 主要 body 字段 |
|---|---|---|---|
| 创建 | POST | /video/generations | model、prompt、duration_sec、frame_images… |
| 查询 | GET | /video/tasks/{taskId} | 路径参数 taskId |
详见 视频生成、高级参数 · 生视频。
分能力文档入口
| 能力 | 端点短页 | 高级参数 |
|---|---|---|
| 生文 | 创建对话补全 | 高级参数 · 生文 |
| 生图（Images） | 创建图像（Images） · 编辑图像（Images） | — |
| 生图（chat） | 创建图像生成（chat） | 高级参数 · 生图 |
| 生视频 | 创建视频生成任务 | 高级参数 · 生视频 |
易混对照
| 你想做的事 | 看的参数 / 文档 |
|---|---|
调 temperature、tools | 高级参数 · 生文 |
| 看图、看视频（输入） | Part · 多模态输入 |
文生图、image_config | 图片生成 |
| 流式打字机效果 | 流式输出（SSE） |
| 超时重试不重复扣费 | X-Idempotency-Key · API 概述 |