通用请求与响应格式¶

API 响应不一定都是 code/msg/data JSON。发送请求前应按接口页设置 Content-Type 和 Accept；收到响应后先检查 HTTP 状态与响应 Content-Type，再按 Genesis 原生对象、Product 包络、JSON-RPC、SSE 或文件流解析。

构造请求¶

请求类型	常用 `Content-Type`	处理方式
JSON 请求	`application/json`	将接口页要求的对象序列化为 JSON，不发送未定义字段。
文件或表单上传	`multipart/form-data`	让 HTTP 客户端生成 boundary；按接口页设置字段名和文件 Part。
二进制包上传	接口指定的媒体类型	原样发送字节流，不再包一层 JSON。
无请求体	不需要设置	不要为了统一客户端而发送空 JSON 对象，除非接口明确要求。

如果希望接收 JSON，可以发送：

Accept: application/json

下载、导出和流式接口可能返回其他媒体类型。客户端应使用实际响应 Header，而不是仅凭路径或请求体猜测返回格式。

Product API 常规响应¶

多数 Product API JSON 接口使用业务包络。当前标准成功响应形如：

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "<RESOURCE_ID>"
  }
}

字段	返回条件	说明
`code`	常规包络返回	业务结果代码。新接口通常以字符串 `OK` 表示成功；兼容接口仍可能使用数字或数字字符串。
`msg` 或 `message`	接口提供说明时返回	面向调用方的结果或错误消息。不能作为稳定程序分支的唯一依据。
`data`	接口有业务结果时返回	资源、列表、任务标识或操作结果。具体结构由接口页定义。
`details`	部分错误返回	结构化错误详情。仅使用接口文档公开的字段。

客户端应先检查 HTTP 状态，再检查包络中的 code。不要只判断 code == 0；当前 Product SDK 为兼容现有接口，会识别 "OK"、0 和 200 等成功形式，但直接使用 HTTP 时仍应以目标接口文档为准。

常规错误响应可能形如：

{
  "code": "ErrParamInvalid",
  "msg": "<ERROR_MESSAGE>",
  "data": null
}

有些认证或兼容接口不会返回完整的 data 字段。错误处理应允许包络中只出现错误码和消息。

Genesis 原生响应¶

Genesis 模型接口按照所选协议返回原生对象，不使用 Product 包络：

接口	主要结果位置
Chat Completions	`choices[].message.content`
Responses	`output[]`
Messages	`content[]`
Embeddings	`data[].embedding`
Rerank	`results[]`
Models	`data[]`

不要把 Chat Completions 的 choices[] 用于解析 Responses 或 Messages。每种协议的完整字段和流式事件由对应 Genesis 接口页维护。

A2A JSON-RPC 响应¶

Product A2A 成功响应直接使用 JSON-RPC，不使用 code/msg/data。例如，发送消息后可能返回任务对象：

{
  "jsonrpc": "2.0",
  "id": "<REQUEST_ID>",
  "result": {
    "kind": "task",
    "id": "<TASK_ID>",
    "status": {
      "state": "working"
    }
  }
}

先检查顶层是否包含 error；成功时再读取 result。JSON-RPC id 用于关联请求，任务 ID 位于 result.id，两者用途不同。完整调用流程见发送消息并启动任务。

SSE 流式响应¶

流式接口通常返回 text/event-stream。客户端需要：

在开始解析事件前检查 HTTP 状态和 Content-Type；
按 SSE 事件边界处理跨网络分片的数据；
按接口协议合并增量，而不是把每个事件当作完整结果；
识别对应协议的结束事件、终止标志或正常 EOF；
在结束事件前发生断开时，将结果标记为中断，不标记为完成。

连接中断后重新发送可能产生重复输出、重复任务或额外模型用量。只有接口支持恢复或应用能够去重时才自动重试。

文件、下载和临时地址¶

下载和导出接口可能返回二进制流、文本流或临时下载地址。处理这类结果时：

检查响应 Content-Type 和文件名相关 Header；
以流式方式写入目标位置，避免把大文件一次性读入内存；
使用后及时关闭响应体；
不在日志或工单中公开临时地址；
如果响应返回异步任务 ID，先等待任务成功，再请求文件结果。

判断请求是否成功¶

按以下顺序判断：

HTTP 请求是否得到可解析响应；
HTTP 状态是否表示成功；
响应媒体类型是否与接口一致；
Product 包络、JSON-RPC 或模型协议是否包含业务错误；
创建或运行类请求是否只完成了提交；
应用需要的字段、任务终态或文件是否已经返回。

HTTP 2xx 不一定表示异步任务已经完成；反过来，客户端超时也不能证明服务端没有创建资源或任务。

下一步¶

最后更新于 2026 年 8 月 14 日