如何集成 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 自动选择模型时，使用 model: "auto"；如需应用对某一指定模型的可复现行为，则填写具体模型 ID。

开始前你需要准备什么？

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

无需一开始就选择所有模型。请先确认 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。

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

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

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

请使用如下基础 URL：

https://api.gate.ai/openai/v1

认证格式如下：

Authorization: Bearer YOUR_API_KEY

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

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

步骤 4：发送首个 API 请求

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

Python 示例：

from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.gate.ai/openai/v1",
)
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 示例：

import OpenAI from "openai";
const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.gate.ai/openai/v1",
});
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 示例：

curl https://api.gate.ai/openai/v1/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：

from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.gate.ai/openai/v1",
)
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 → 设置 → 路由 管理。

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

应选择哪种集成方式？

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

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

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

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

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

后续可配置哪些内容？

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

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

常见问题解答

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

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

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

可以。Gate.AI 支持 OpenAI 兼容 API 格式，只需设置 Gate.AI API 密钥并将基础 URL 替换为 https://api.gate.ai/openai/v1。

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

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

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

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