一套 API 调用多个 AI 模型：模型聚合平台接入指南

先说结论

当应用需要同时调用对话、图像和视频模型时，最难维护的往往不是某一次请求，而是多套密钥、不同参数、异步任务和错误处理。统一模型 API 的作用，是把模型发现、认证、任务提交、计费和状态查询收敛成一套流程。

墨智 AI 开放 API 的最小闭环只有四个接口：

1. GET /v1/models 查询可用模型；
2. GET /v1/models/:id 获取模型参数；
3. POST /v1/generations 提交生成任务；
4. GET /v1/generations/:id 查询异步任务。

这是一套统一任务 API，并不意味着任何第三方 SDK 都能在不修改代码的情况下直接替换 Base URL。接入前应以开放 API 文档中的实际请求结构为准。

为什么需要模型聚合层

直接对接单个厂商适合验证想法，但模型数量增加后，应用通常会遇到：

• 每个厂商使用不同的密钥和鉴权方式；
• 文本请求同步返回，图片和视频需要异步轮询；
• 参数名称、结果结构和错误码不同；
• 模型升级或下线时需要修改业务代码；
• 成本、额度和调用记录分散在多个平台。

聚合层不会消除模型之间的能力差异，但能把公共流程统一。业务代码仍然要理解每种模型的参数和输出特点。

第一步：创建并保存 API Key

登录后前往API 密钥页面创建密钥。完整密钥只在创建时展示一次，应立即保存到密码管理器或部署平台的环境变量中。

export MOZHIAI_API_KEY="sk-mozhiai-xxxxxxxxxxxxxxxx"

不要把真实密钥写进源码、博客、日志或 Git 仓库。开发环境和生产环境应使用不同密钥，便于设置额度、单独轮换和出现泄露时快速吊销。

每个请求通过 Bearer Token 认证：

Authorization: Bearer YOUR_API_KEY

第二步：查询当前可用模型

模型名称、状态和参数可能变化，因此不要在代码里长期硬编码一份模型清单。先调用模型列表：

curl "https://api.mozhiai.net/v1/models" \
  -H "Authorization: Bearer $MOZHIAI_API_KEY"

可以使用 type 按模型类型过滤，使用 q 按关键词搜索：

curl "https://api.mozhiai.net/v1/models?type=image&q=banana" \
  -H "Authorization: Bearer $MOZHIAI_API_KEY"

从响应中取得模型 id。它是字符串形式的雪花 ID，后续提交任务时也必须按字符串传递，不能转换成 JavaScript 的普通数字。

更完整的字段说明见模型列表接口。

第三步：读取模型参数

不同模型支持的比例、尺寸、时长和参考图数量不同。选择模型后，读取模型详情与参数定义：

curl "https://api.mozhiai.net/v1/models/1234567890" \
  -H "Authorization: Bearer $MOZHIAI_API_KEY"

前端可以根据返回的 parameters 动态生成表单，后端也可以在提交前校验用户参数。这样模型参数调整时，不必在多个客户端重复维护枚举值。

第四步：提交生成任务

所有生成任务都提交到 POST /v1/generations：

curl -X POST "https://api.mozhiai.net/v1/generations" \
  -H "Authorization: Bearer $MOZHIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "1234567890",
    "prompt": "一只戴宇航头盔的柯基，赛博朋克风格",
    "input_file_urls": [],
    "params": {
      "size": "1024x1024"
    }
  }'

四个核心字段分别是：

调用方不需要在请求中指定上游渠道。渠道策略配置在 API Key 上，由平台按密钥策略选择可用渠道。

第五步：处理同步与异步结果

提交成功后先检查响应中的 status：

• completed：任务已经同步完成，直接读取 output_result；
• pending 或 processing：任务仍在执行，保存任务 id 并轮询；
• failed 或 cancelled：任务已经进入终态，不再继续轮询。

图片和视频等耗时任务通常需要查询：

curl "https://api.mozhiai.net/v1/generations/1234567890123456" \
  -H "Authorization: Bearer $MOZHIAI_API_KEY"

轮询间隔建议不小于 3 秒，进入终态后立即停止。生产代码还应设置总超时时间，避免网络异常或上游故障导致无限轮询。

TypeScript 最小调用示例

const baseURL = "https://api.mozhiai.net/v1";
const apiKey = process.env.MOZHIAI_API_KEY;

if (!apiKey) throw new Error("缺少 MOZHIAI_API_KEY");

const headers = {
  Authorization: `Bearer ${apiKey}`,
  "Content-Type": "application/json",
};

const response = await fetch(`${baseURL}/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model_id: "1234567890",
    prompt: "雨夜的未来城市，电影感广角镜头",
    input_file_urls: [],
    params: {},
  }),
});

const envelope = await response.json();
if (!response.ok || envelope.code !== 0) {
  throw new Error(envelope.message ?? "生成任务提交失败");
}

console.log(envelope.data);

密钥只能保存在服务端环境变量中。不要在浏览器代码里放入 API Key，否则任何访客都可能通过开发者工具读取并盗用。

生产环境必须补上的能力

教程代码只覆盖最小闭环。正式接入还需要：

超时与重试

网络错误、502 和 503 可以采用带随机抖动的指数退避；参数错误、鉴权失败和余额不足通常不应原样重试。提交任务超时后，要先判断平台是否已经创建任务，避免重复计费。

幂等与业务记录

在自己的数据库保存业务订单号、模型 ID、平台任务 ID、提交时间和最终状态。用户刷新页面后，应根据任务 ID恢复查询，而不是再次提交。

结果结构适配

output_result 会因模型和厂商而异。建议在业务层把文本、图片 URL、视频 URL 和原始结果转换成自己的统一结构，同时保留原始响应便于排查。

配额与成本保护

为不同应用创建独立密钥并设置额度上限；记录每次响应的 cost_amount；批量任务设置并发、最大重试次数和预算告警。

模型降级

为关键业务准备一个能力接近的备用模型。降级前检查输入参数是否兼容，不要只替换 model_id 就假设输出完全一致。

常见问题

能否用一个 API Key 调用所有模型

一个墨智 AI API Key 可以访问平台向该账户开放的模型，但具体可用范围、余额、额度和渠道状态仍会影响调用结果。运行时应以模型列表接口为准。

为什么模型 ID 必须是字符串

模型 ID 使用雪花 ID，可能超出 JavaScript 安全整数范围。以字符串传递可以避免精度丢失。

文本、图片和视频的调用方式完全相同吗

提交入口统一，但参数、结果结构和执行时长不同。文本任务可能同步完成，图片和视频通常需要异步轮询，因此业务层仍需按模型类型处理结果。

继续接入

• 五步快速开始
• API Key 认证与轮换
• 提交生成任务接口
• 查询任务状态接口
• 浏览当前模型