# 通用请求与响应格式

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，可以发送：

```http
Accept: application/json
```

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

## Product API 常规响应

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

```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 时仍应以目标接口文档为准。

常规错误响应可能形如：

```json
{
  "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`。例如，发送消息后可能返回任务对象：

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

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

## SSE 流式响应

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

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

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

## 文件、下载和临时地址

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

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

## 判断请求是否成功

按以下顺序判断：

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

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

## 下一步

- [处理分页、异步任务与幂等](pagination-async-idempotency.md)
- [处理状态码与错误码](status-error-codes.md)
- [查看 Product API 任务入口](../product-api/index.md)