# API 通用规则

本节说明 Genesis 模型 API 与 Product API 之间可以共享的客户端处理方法。它不会覆盖两类 API 的认证差异，也不替代具体接口的参数和响应参考。

## 建议阅读顺序

1. 从[服务地址与环境](service-endpoints-environments.md)确认正在调用 Genesis 还是 Product API，并正确拼接接口地址。
2. 按[身份认证](authentication.md)选择凭据、认证 Header 和 Product 工作区作用域。
3. 使用[请求与响应格式](request-response-formats.md)判断响应属于 Product 包络、Genesis 原生对象、JSON-RPC、SSE 还是文件流。
4. 调用列表或执行类接口时，按[分页、异步任务与幂等](pagination-async-idempotency.md)继续读取结果并避免重复写入。
5. 请求失败后，先按[状态码与错误码](status-error-codes.md)分类，再决定是否使用[限流与重试](rate-limits-retries.md)中的恢复策略。
6. 发布和升级客户端前，检查[版本与兼容性](versions-compatibility.md)。

## 页面职责

| 页面 | 解决的问题 |
| --- | --- |
| [服务地址与环境](service-endpoints-environments.md) | 怎样选择和拼接 Base URL，以及切换环境时需要一起更新哪些值。 |
| [身份认证](authentication.md) | Genesis 与 Product API 分别使用什么凭据、Header 和作用域。 |
| [请求与响应格式](request-response-formats.md) | 怎样构造 JSON、上传或流式请求，并选择正确的响应解析方式。 |
| [分页、异步任务与幂等](pagination-async-idempotency.md) | 怎样继续翻页、跟踪任务，并处理超时和重复提交。 |
| [状态码与错误码](status-error-codes.md) | 怎样结合 HTTP、业务包络和协议对象判断错误。 |
| [限流与重试](rate-limits-retries.md) | 哪些请求可以重试，以及怎样设置有边界的等待策略。 |
| [版本与兼容性](versions-compatibility.md) | 怎样保持地址、协议和 SDK 版本一致，并安全升级客户端。 |

需要准确的方法、路径、参数和响应字段时，请进入 [Genesis 模型 API](../genesis-model-api/index.md)或 [Product API](../product-api/index.md) 的对应接口页。

```{toctree}
:hidden:
:maxdepth: 1

服务地址与环境 <service-endpoints-environments>
身份认证 <authentication>
请求与响应格式 <request-response-formats>
分页、异步任务与幂等 <pagination-async-idempotency>
状态码与错误码 <status-error-codes>
限流与重试 <rate-limits-retries>
版本与兼容性 <versions-compatibility>
```