如何集成 Gate.AI：开发者快速入门

Gate.AI API 集成让开发者能够通过兼容 OpenAI 的 API 访问多种 AI 模型，实现统一的模型接入、路由和测试，无需为每个模型服务商单独维护 SDK 配置。无论是开发聊天机器人、内部工具、智能代理、流程自动化，还是模型评测脚本，都能大幅简化接入流程。本指南将介绍 API 密钥创建、自动路由、手动模型选择、OpenAI 兼容基础 URL、首次请求测试及常见配置错误排查，但不涵盖企业级治理、计费策略设计或自定义安全架构等高级主题。

前置条件：

• 拥有 Gate.AI 账户并可访问 Console 设置。
• 本地环境已配置 Python、Node.js 或 curl。

完成本指南后你将获得哪些能力？

完成本指南后，你将能够创建 Gate.AI API 密钥，配置 OpenAI 兼容基础 URL，使用 model: "auto" 发送首个 API 请求，并测试指定模型 ID。

开发者通过 Gate.AI API 集成可以构建哪些应用？

开发者可利用 Gate.AI API 集成，通过统一的 OpenAI 兼容请求格式访问多模型体系，典型应用场景包括：

| 构建类型 | Gate.AI 的作用 | 示例输出 | | ------------------ | ------------------------------------- | ------------------------------- | | 聊天应用 | 将用户消息路由至支持的聊天模型 | 客服助理 | | 内部工具 | 团队间统一 API 配置 | AI 写作/研究助手 | | 智能代理与流程 | 连接模型调用与任务自动化 | 工具调用助理 | | 模型测试 | 对比 auto 路由与固定模型 ID | 评测脚本 | | 迁移项目 | 替换现有 OpenAI 兼容基础 URL | 多模型原型 |

当你希望 Gate.AI 自动选择模型时，使用 model: "auto"；如需应用对某一指定模型的可复现行为，则填写具体模型 ID。

开始前你需要准备什么？

启动前仅需满足两个关键条件：

| 必要条件 | 重要原因 | | ------------------ | ----------------------------------------------------- | | Gate.AI 账户访问 | 需进入 Console 创建 API 密钥并检查路由设置 | | 本地请求方式 | 需通过 Python、Node.js 或 curl 发送测试请求 |

无需一开始就选择所有模型。请先确认 API 密钥和基础 URL 可用，再测试手动模型选择。

步骤 1：创建 Gate.AI API 密钥

本步骤将创建你应用用于 API 认证的凭证。

操作方法：

1. 访问 gate.ai。
2. 选择登录方式并完成授权。
3. 打开 Console → 设置 → API keys。
4. 点击 创建密钥。
5. 立即复制 API 密钥并妥善保存。

你将在 API 密钥区域看到新密钥。如 secret 仅显示一次，请务必在关闭创建窗口前复制密钥。

步骤 2：选择自动路由或手动模型选择

本步骤决定由 Gate.AI 自动分配模型，还是在请求中指定模型。

操作方法：

1. 打开 Console → 设置 → 路由。
2. 检查 自动路由 开关。
3. 若需 Gate.AI 为每次请求自动选择模型，保持自动路由开启。
4. 如需手动指定模型 ID，则关闭自动路由，在请求体中填写模型 ID。

| 选择模式 | 请求参数值 | 适用场景 | | ------------------ | ------------------------------------------ | ----------------------------------------- | | 自动路由 | "model": "auto" | 需 Gate.AI 自动路由请求时 | | 手动模型选择 | "model": "anthropic/claude-sonnet-4.6" | 需测试或使用指定模型 ID 时 |

自动路由适合快速接入和通用路由测试；手动选择适用于需对单一模型进行可复现评测的场景。

步骤 3：配置 OpenAI 兼容基础 URL

本步骤将现有 OpenAI 风格客户端指向 Gate.AI，而非默认 OpenAI 端点。

请使用如下基础 URL：

text

认证格式如下：

text Authorization: Bearer YOUR_API_KEY

Gate.AI 文档规定 API 路径为 /openai/v1，而非仅 /v1（截至 2026年6月）。请严格按照示例填写完整基础 URL。

| 配置项 | 值 | | ------------------ | ------------------------------------------ | | 基础 URL | | | 认证方式 | Authorization: Bearer YOUR_API_KEY | | 格式 | 兼容 OpenAI | | 聊天端点 | POST /chat/completions | | 模型列表端点 | GET /models |

大多数集成错误源于基础 URL 缩写或 API 密钥复制错误。请先确认这两项无误，再调整模型配置。

步骤 4：发送首个 API 请求

本步骤用于测试 API 密钥、基础 URL 及 OpenAI 兼容聊天格式是否协同工作。

Python 示例：

python from openai import OpenAI

client = OpenAI( api_key="YOUR_API_KEY", base_url="", )

completion = client.chat.completions.create( model="auto", messages=[ {"role": "system", "content": "You are a concise assistant."}, {"role": "user", "content": "Say hello from Gate.AI."} ], )

print(completion.choices[0].message.content)

Node.js 示例：

javascript import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "", });

const completion = await client.chat.completions.create({ model: "auto", messages: [ { role: "system", content: "You are a concise assistant." }, { role: "user", content: "Say hello from Gate.AI." } ], });

console.log(completion.choices[0].message.content);

curl 示例：

bash curl /chat/completions
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "auto", "messages": [ {"role": "system", "content": "You are a concise assistant."}, {"role": "user", "content": "Say hello from Gate.AI."} ] }'

你应收到正常的助手回复。如遇认证错误，请先检查 API 密钥，无需立即修改代码。

步骤 5：测试指定模型 ID

本步骤验证在应用需要指定模型时，手动模型选择是否生效。

将 model 参数由 auto 改为具体支持的模型 ID：

python from openai import OpenAI

client = OpenAI( api_key="YOUR_API_KEY", base_url="", )

completion = client.chat.completions.create( model="anthropic/claude-sonnet-4.6", messages=[ {"role": "user", "content": "Explain model routing in one paragraph."} ], )

print(completion.choices[0].message.content)

请严格按照 Gate.AI 模型文档或模型列表中的名称填写模型 ID。如拼写错误，即使 API 密钥和基础 URL 正确，请求也会失败。

Gate.AI API 请求中的自动路由机制如何工作？

Gate.AI 自动路由通过在请求体中填写 model: "auto"，并结合 Gate.AI 控制台中的路由配置，为请求自动选择模型。截止 2026年6月，相关路由控制项可在 Console → 设置 → 路由 管理。

| 路由方式 | 配置位置 | API 请求参数 | | ------------------ | ------------------------------------ | ----------------------------- | | 自动路由 | Console → 设置 → 路由 | "model": "auto" | | 手动模型选择 | 请求体 | 指定模型 ID | | 路由策略控制 | 控制台路由设置 | 组织自定义行为 |

自动路由并不等同于省略模型字段。需在请求中明确填写 model 字段并赋值为 auto，Gate.AI 才会自动路由。

应选择哪种集成方式？

请根据应用运行环境选择集成方式：

| 方式 | 适用场景 | 主要变更点 | | ------------------------------ | ----------------------------------------- | --------------------------------- | | Python SDK | 已有 Python 后端脚本或服务 | 设置 base_url 和 api_key | | Node.js SDK | 使用 JavaScript 或 TypeScript 服务 | 设置 baseURL 和 apiKey | | curl | 需最快速手动验证 | 直接发送请求头和 JSON 载荷 | | 现有 OpenAI 兼容应用 | 应用已支持自定义基础 URL | 替换基础 URL 和 API 密钥 |

多数开发者推荐先用 curl 快速验证，随后用 Python 或 Node.js 集成到实际应用。

Gate.AI API 请求失败的常见原因有哪些？

集成遇阻时，请按下表逐项排查：

| 症状 | 原因说明 | 解决方法 | | -------------------------------------- | ---------------------------------------------------- | -------------------------------------------------- | | 401 或 API 密钥无效 | API 密钥缺失、过期、复制错误，或未用 Bearer 认证 | 重新创建/复制密钥，使用 Authorization: Bearer YOUR_API_KEY | | 找不到模型 | 请求使用了错误或账户不可用的模型 ID | 查阅 Gate.AI 模型文档，或用 model: "auto" 路由测试 | | OpenAI 兼容代码立即报错 | 基础 URL 不完整或仅填写了 /v1 | 使用 | | 自动路由未按预期工作 | 自动路由被关闭或路由设置与预期不符 | 打开 Console → 设置 → 路由 检查自动路由开关 | | 响应为空或异常 | 请求体格式错误或所选模型不支持当前请求 | 先测试最简聊天请求，再逐步添加参数 |

排查建议依次从认证、基础 URL、模型 ID 开始。大部分快速接入问题可通过这三步解决。

后续可配置哪些内容？

首次请求成功后，开发者可从以下三个方向拓展集成：

• 在 Gate.AI 控制台配置模型路由行为：
• 查看模型可用性并为生产测试选择固定模型 ID：
• 对比价格，合理选择高并发场景下的模型：

常见问题解答

为什么建议优先使用 model: "auto"？

优先用 model: "auto" 可一次性验证 API 密钥、基础 URL、请求格式和路由配置。确认无误后，再测试指定模型 ID。

可以用现有 OpenAI SDK 调用 Gate.AI 吗？

可以。Gate.AI 支持 OpenAI 兼容 API 格式，只需设置 Gate.AI API 密钥并将基础 URL 替换为 。

切换到指定模型后请求失败的原因？

模型 ID 可能不存在、拼写错误，或当前账户不支持。请在 Gate.AI 模型文档中确认模型 ID 后重试。

使用指定模型时需要关闭自动路由吗？

不一定。当需要手动选择模型时，可直接在请求体中传入模型 ID。如行为与预期不符，请检查控制台路由设置。