CmlAI 开发者 API 对接指南

1. 简介

CmlAI 平台为您提供了一个统一的、遵循 OpenAI 兼容规范 的 API 接口。无论您希望接入海外先进大语言模型（如 GPT-4、Claude 3 等）还是国内主流大模型（如 豆包、DeepSeek、Kimi 等），您都可以使用同一套代码逻辑进行调用，无需针对各个供应商编写不同的适配代码。

2. 基础配置

2.1 API Base URL

所有 API 的基础地址为 CmlAI 提供给您的服务地址（如 https://api.cmlai.com/v1 或您的私有部署地址）。在使用各类 SDK 时，请务必将默认的 OpenAI 域名替换为 CmlAI 的域名。

2.2 鉴权方式 (Authentication)

CmlAI 使用标准的 Bearer Token 形式进行身份验证。您需要在您的控制台页面生成一个 API Key，并在每个 HTTP 请求的 Authorization 请求头中携带该 Key。

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

---

3. 快速开始与常见场景

3.1 文本对话 (Chat Completions)

这是最基础的文本交互接口。常用于聊天机器人、问答、文本总结等需求。

Request URL:POST /v1/chat/completions

请求示例 (cURL):

curl --location 'https://api.cmlai.com/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-your-cmlai-api-key' \
--data '{
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "你是一个非常有用的编程助手。"},
        {"role": "user", "content": "请用Python写一个简单的二分查找。"}
    ],
    "stream": false
}'

主流 SDK 对接示例 (Python):

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-cmlai-api-key",
    base_url="https://api.cmlai.com/v1"
)

response = client.chat.completions.create(
    model="deepseek-chat", # 这里可以随意切换国内/国外模型
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己。"}
    ]
)
print(response.choices[0].message.content)

3.2 流式输出 (Streaming)

当您需要搭建类似 ChatGPT 的打字机效果时，可以在请求体中加上 "stream": true。

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "写一首关于秋天的诗。"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

---

4. 模型名称规范

CmlAI 的优势之一是通过一个网关访问多种不同厂商的模型，您只需更改 model 参数即可：

• OpenAI 体系: gpt-3.5-turbo, gpt-4o, gpt-4-turbo
• Anthropic 体系: claude-3-opus-20240229, claude-3-sonnet-20240229
• 国内主流模型: doubao-pro-32k, deepseek-chat, moonshot-v1-8k (具体可用模型名称请参照 CmlAI 控制台的模型列表)。

---

5. 高级功能

5.1 智能路由与自动容灾

CmlAI 在后台已经为您配置了多个通道的负载均衡与自动重试逻辑。因此，当上游服务抖动时，您的 API 请求会自动切换到健康的候选节点，无需您在代码层面实现复杂的重试机制。

5.2 多模态与函数调用 (Function Calling)

CmlAI 完全兼容标准协议的多模态以及 Function Calling。您可以直接根据 OpenAI 的官方文档，向 gpt-4o 传递 tools 字段或向支持视觉处理的模型传递 image_url，CmlAI 将完整透传和处理。

---

6. 常见错误码

遵守通用的 HTTP 状态码规范：

• 401 Unauthorized：API Key 缺失、错误或者已被禁用。
• 402 Payment Required：账号余额不足或额度已用尽。
• 403 Forbidden：IP 不在白名单或您的账号权限不足以调用当前模型。
• 429 Too Many Requests：超出了并发限制或 RPM(请求数/分钟) / TPM(Token数/分钟) 限制。
• 500/502/503/504：上游通道或者中继网关暂时无响应，请查看错误详情或联系管理员。

7. 获取支持

在接入过程中，如果您遇到任何困难或发现模型调用异常，请随提供对应的 x-request-id，并联系 support@cmlai.com 获取专属工程师支持。