请求约定

不同协议的请求体不同，但生产客户端可以遵循一组共同原则。

Content-Type

JSON 接口通常使用：

Content-Type: application/json

上传文件或多媒体时，应使用对应接口要求的 multipart/form-data 或其他格式。

模型字段

不要假设模型 ID 永远固定。

{
  "model": "YOUR_MODEL_ID"
}

推荐从配置读取模型 ID，并定期根据平台实际可用模型校验。

API Key

优先通过请求头传递凭证，不要把 API Key 放在 URL 中。

OpenAI 兼容：

Authorization: Bearer YOUR_API_KEY

Anthropic：

x-api-key: YOUR_API_KEY

Gemini：

x-goog-api-key: YOUR_API_KEY

Streaming

流式响应需要客户端处理：

• 长连接
• 分块数据
• 中途断线
• 客户端取消
• 首字节和整体超时

收到部分内容后连接中断时，不应自动假设整个请求“从未执行”。

请求大小

服务端包含请求体大小保护。图片、音频、Base64、多轮上下文和工具定义都可能快速增大请求体。

超大请求应尽量：

• 压缩输入
• 避免重复上下文
• 使用更合适的媒体格式
• 将大型任务拆分

幂等与重复请求

很多生成接口本质上是有副作用或有成本的 POST 请求。

如果网络超时发生在服务端已接受请求之后，简单重放可能产生第二次调用。

业务端可以使用自己的 request_id、任务表或状态机来避免重复执行。

时间与编码

• JSON 使用 UTF-8。
• 时间字段如由具体接口定义，应按对应协议要求发送。
• 不要依赖客户端本地时区推断账务或日志时间，排查时优先使用明确时间范围。

兼容字段

某协议支持某字段，不代表所有模型都支持。

建议：

1. 从最小请求开始。
2. 每次只增加一类高级能力。
3. 出错后回退到最小请求定位。