云器科技-文档

适用范围

本文帮助第一次使用 AI Gateway 的用户完成一次完整调用。模型的实际调用地址、模型标识和参数格式，以模型详情页展示的最新示例为准。

一、开始前需要准备什么

开始前，请确认：

已经登录 AI Gateway；
已经获得 AI Gateway 账号；
已经明确当前业务使用场景；
已经判断应使用经济型、标准型还是高质量型；
已经确认账号具备创建 API Key 的权限。

如果是正式生产系统、自动化 Agent 或其他产品的内嵌调用，建议优先使用高质量型。

二、快速开始的完整路径

选择服务档位 ↓ 创建 API Key ↓ 选择模型 ↓ 查看模型详情 ↓ 复制调用示例 ↓ 选择已经创建的 API Key ↓ 运行示例 ↓ 查看用量统计

三、第一步：选择服务档位

先根据业务重要程度判断服务档位。

业务情况	建议档位
临时测试、个人试用、非关键任务	经济型
日常工具、常规内部业务	标准型
正式生产、自动化 Agent、多步骤任务	高质量型

高质量型可以理解为更稳定的服务链路。

如果账号没有任何生效的专属折扣，默认按照刊例价计费。创建其他档位的 API Key 不依赖是否存在折扣；但账号一旦配置过任意模型折扣，模型必须在当前 API Key 档位配置生效折扣才能使用，其他档位的折扣不能复用。

请注意：系统不会因为当前档位不可用而自动切换到其他档位。当前档位没有可用服务时，本次请求会失败。

四、第二步：创建 API Key

进入 API Key 管理 页面，点击新建。

建议按照业务或应用填写名称，例如：

```
data-analytics-agent
```
data-analytics-agent
；
```
engineering-agent
```
engineering-agent
；
```
cz-cli
```
cz-cli
；
```
lakehouse-ai-function
```
lakehouse-ai-function
；
```
model-test
```
model-test
。

创建时选择服务档位。

一个 API Key 对应一个服务档位。如果一个业务需要使用多个档位，请分别创建多个 API Key。

创建 API Key 时不需要填写模型折扣，具体模型折扣和价格可在模型广场中查看。

配图 1：新建 API Key 页面

创建成功后，请妥善保存 API Key。API Key 等同于业务调用凭证，不要直接提交到公开代码仓库或发送到不受控的群聊中。

五、第三步：在模型广场选择模型

进入 模型广场，根据任务选择模型。

建议重点查看：

模型名称；
模型适用场景；
模型刊例价；
当前账号的档位折扣；
是否标记为“全价”；
模型详情中的调用方式。

如果账号没有任何生效的专属折扣，所有模型都可以使用，页面会展示刊例价并标记为“全价”。如果账号已经配置过任意模型折扣，当前模型在当前 API Key 档位没有折扣时会标记为“不可用”，不能调用，即使该模型在其他档位有折扣也一样。

配图 2：模型广场卡片

六、第四步：打开模型详情

点击模型卡片进入模型详情页。

模型详情页通常包含：

模型基础信息；
模型标识；
适用场景和能力说明；
刊例价；
已配置档位的折后价；
“全价”提示；
调用示例；
当前模型的监控入口。

如果某个档位没有配置折扣，详情页不展示该档位的折后价。账号没有任何生效专属折扣时，详情页保留统一刊例价并标记“全价”；账号已有任意模型折扣时，当前模型在该档位没有折扣就标记为“不可用”。

七、第五步：复制调用示例

在模型详情页选择需要的调用方式，例如 cURL 或 Python。

复制示例时，可以选择已经创建的 API Key，生成可直接用于测试的请求代码。

下面是请求结构示意，不能直接执行。实际地址、模型标识和参数请从模型详情页复制完整示例：

curl -X POST https\://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions \\ \-H "Authorization: Bearer $API\_KEY" \\ \-H "Content-Type: application/json" \\ \-d '{ "model": "minimax/MiniMax-M2.5", "messages": \[{"role":"user","content":"hello"}] }'

配图 3：模型详情页调用示例

八、第六步：运行第一次调用

将模型详情页的最新示例复制到本地终端或业务代码中，替换必要的业务参数，然后执行调用。

第一次调用建议使用简单输入，例如：

请用一句话介绍你自己。

如果调用成功，说明以下基础链路已经打通：

账号访问 ↓ API Key 鉴权 ↓ 服务档位识别 ↓ 模型调用 ↓ 结果返回

九、第七步：查看调用结果和用量

调用完成后进入 用量统计，查看：

请求次数；
Token 总量；
输入和输出 Token；
成功率；
错误率；
响应延迟；
不同时间范围的使用变化。

配图 4：用量统计首页

十、第一次调用失败时怎么排查

按以下顺序检查：

1. API Key 是否正确

确认请求中使用的是完整、有效且未停用的 API Key。

2. API Key 是否选择了正确档位

一个 API Key 对应一个服务档位。确认当前业务没有误用测试 Key 或其他业务的 Key。

3. 模型标识是否正确

模型标识以模型详情页为准，不建议手动猜测或长期复用旧标识。

4. 请求地址是否正确

使用模型详情页最新示例中的请求地址。

5. 请求参数是否符合模型要求

不同模型可能支持不同的输入内容和参数。优先从详情页示例开始，再逐步增加业务参数。

6. 当前档位是否有可用服务

AI Gateway 不会自动跨档位切换。当前档位不可用时，本次请求会失败。

十一、正式接入前的建议

正式上线前建议完成以下准备：

为每个产品创建独立 API Key；
正式业务优先选择高质量型；
不把 API Key 写入公开代码仓库；
在用量统计中确认调用量和错误率；
为团队成员配置合适的访问权限；
记录模型详情页中的最新调用方式。