SDK

SDK 是 Software Development Kit 的缩写。在模型 API 场景中，它指官方为 Python、JavaScript 等语言提供的客户端库：内部仍然是发 HTTP 请求，但把认证、参数序列化、流式响应解析、错误类型映射与重试封装成了方法调用。用 SDK 还是直接发 HTTP 请求，取决于你需要多少控制权。

它替你做了什么

• 认证：从环境变量读取密钥并自动加上认证请求头。
• 请求构造：把方法参数序列化成合法的请求体。
• 流式解析：把服务端推送的增量事件拼成可迭代的对象，不用自己处理分块。
• 错误分类：把状态码映射成不同的异常类型，认证失败、限流、上游故障可以分开处理。
• 重试与超时：多数官方 SDK 内置了基础的退避重试。

常见误解

• SDK 不是另一套 API。 它底层仍然是同一批 HTTP 接口，能力上限由接口决定，不会因为换 SDK 多出功能。
• 装错包是新手最常见的坑。 同一家厂商可能存在新旧两个包名，照着旧教程安装会发现文档里的方法都找不到。
• SDK 支持改地址，不代表对面完全兼容。 官方 SDK 允许覆盖 Base URL，这正是第三方兼容服务的接入方式，但参数行为是否一致要另行验证。

什么时候不用 SDK

只想确认链路是否通、或者在受限环境里做一次性调用时，直接发 HTTP 请求更简单。需要精确控制超时、连接复用或自定义重试策略时，也常见直接用 HTTP 客户端。

本站三篇官方 API 教程都以官方 SDK 为主线，同时给出等价的 HTTP 调用作为对照。