> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rockapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 兼容 API 迁移：Python、Node.js 与验收清单

> 配置 Python、Node.js 和 curl 连接兼容网关，逐项验证模型权限、流式输出、工具调用、错误处理及结算用量。

**OpenAI 兼容 API**支持文档约定的 OpenAI 风格请求与响应，可让应用在已支持的操作上复用客户端。但修改 Base URL 只是迁移起点：模型 ID、参数、工具调用、流式事件和错误处理，都需要单独验收，不能据此承诺零改动上线。

## 准备账户与请求参数

在[当前模型目录](https://rockapi.ai/pricing)选择支持聊天的模型，复制完整 ID，并确认账户和分组可用。在[API 密钥页面](https://rockapi.ai/keys)创建 Rock API 平台密钥，不能直接用原供应商密钥替代。测试前阅读[计费说明](https://docs.rockapi.ai/zh-cn/pricing-and-billing.md)，确认余额要求。

把密钥保存在服务端环境变量 `ROCK_API_KEY`，把所选 ID 设置为 `ROCK_API_MODEL`。下面的示例要求本地有 curl，或在对应语言环境中已安装 `openai` 包。它们演示 Chat Completions，不代表所有 SDK 方法或供应商原生接口都已支持。普通买家无需配置上游渠道。

## 先建立最小调用基线

SDK 的完整 Base URL 为 `https://rockapi.ai/v1`。不要再追加一个 `/v1`，也不要把 `/chat/completions` 填进 SDK 的基础地址。curl 使用完整端点：

```bash theme={null}
curl --fail-with-body https://rockapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$ROCK_API_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"请回复你好。\"}]}"
```

### Python 示例

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://rockapi.ai/v1",
    api_key=os.environ["ROCK_API_KEY"],
)
response = client.chat.completions.create(
    model=os.environ["ROCK_API_MODEL"],
    messages=[{"role": "user", "content": "请回复你好。"}],
)
print(response.choices[0].message.content)
```

### Node.js 示例

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://rockapi.ai/v1",
  apiKey: process.env.ROCK_API_KEY,
});
const response = await client.chat.completions.create({
  model: process.env.ROCK_API_MODEL,
  messages: [{ role: "user", content: "请回复你好。" }],
});
console.log(response.choices[0].message.content);
```

## 逐项验收应用使用的功能

先不带可选参数，再逐个加入真实业务所需功能。记录 SDK 版本、模型 ID、输入和预期结果，方便失败时复现。

| 检查项 | 需要的验收证据 |
| - | - |
| 基础响应 | 依赖字段完整、内容可用、结束原因符合预期 |
| 流式输出（如支持） | SSE 解析、完成、取消和中断处理正确 |
| 工具调用（如支持） | 参数校验、工具返回及后续模型轮次通过 |
| 结构化或多模态输出 | 应用实际使用的结构或媒体输入通过 |
| 错误与限制 | 能处理无效输入、权限不足、超时与 `429` |
| 计费 | 控制台存在匹配记录，类别、分组和结算金额可核对 |

文本调用成功并不能证明图片或工具调用成功。同一端点下的不同模型，仍可能有不同功能和输出行为，可参考[按任务评估模型](https://docs.rockapi.ai/zh-cn/blog/buyers/ai-model-api-comparison.md)。

## 保留回滚路径再逐步放量

在测试环境回放经过脱敏的真实请求，比较质量、延迟、错误和每个合格结果的费用。检查重试上限，避免重复执行或无控制地消费；鉴权失败不应无限重试。按[错误与限流说明](https://docs.rockapi.ai/zh-cn/errors-and-rate-limits.md)排查，并保留不含密钥或私密提示词的时间戳和请求 ID。

验收通过后再逐步增加生产流量，保留原配置用于回滚。核账以最终用量记录为依据，临时扣减和 HTTP 错误均不能单独证明最终收费结果。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.