API 调用方法

本页说明所有 SDKMAX 接口通用的调用约定：地址、鉴权、请求/响应格式、流式输出、限流与重试。

基础地址

https://api.sdkmax.com/v1

所有 OpenAI 兼容接口都挂载在 /v1 前缀下，例如 /v1/chat/completions、/v1/embeddings、/v1/images/generations。

鉴权

在请求头中携带 API Key：

Authorization: Bearer sk-你的密钥

未携带、Key 已禁用/过期/额度耗尽，都会返回 401 或 403，具体见 错误码。

请求格式

• Content-Type: application/json（文件上传类接口如图片编辑、语音转写除外，使用 multipart/form-data）。
• 请求体字段与 OpenAI 官方文档保持一致，例如 model、messages、temperature、max_tokens、stream 等。

curl https://api.sdkmax.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}],
    "temperature": 0.7
  }'

响应格式

正常响应与 OpenAI 保持一致的 JSON 结构，例如 chat/completions 返回：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好！有什么可以帮你的？" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}

错误响应统一为：

{
  "error": {
    "message": "错误描述（含请求 ID，便于排查）",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

流式输出（SSE）

将 stream 设为 true 即可获得 Server-Sent Events 流式响应，协议与 OpenAI 一致：

{ "model": "gpt-4o", "messages": [...], "stream": true }

客户端按行读取以 data: 开头的 JSON 片段，直到收到 data: [DONE] 表示流结束。使用官方 OpenAI SDK 时，流式处理方式与直连 OpenAI 完全相同，无需额外适配。

限流与配额

• 每个 API Key 可在创建时设置额度上限，额度耗尽后调用返回 429（或 403，取决于配置的限制类型）。
• 平台可能对单 Key/单账户设置请求速率限制，短时间内请求过多同样返回 429。
• 建议客户端对 429/5xx 做指数退避重试（例如首次等待 1s，失败后翻倍，设置最大重试次数）。

模型可用性

调用 GET /v1/models 可获取当前网关实际可用的模型列表（随上游渠道自动同步，随时可能变化）：

curl https://api.sdkmax.com/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

幂等与重试建议

• 网络超时/5xx 错误：可安全重试（幂等的 GET 类请求，或未产生副作用的失败请求）。
• 4xx 客户端错误（如 400/401/404）：先修正请求本身，重试不会成功。
• 长时间任务（图片/视频生成）：接口通常返回一个任务 ID，需要轮询单独的结果查询接口，参见 图片 API 和 视频 API。

下一步

• 查看接口兼容范围：OpenAI 兼容接口
• 直接用官方 SDK：Python · Node.js · Java · Go