MModelGrid
开发文档

从 API Key 开始接入模型能力

真实业务通常在本地脚本、后端服务或自有服务器调用 ModelGrid API。控制台用于创建 Key、查看余额、流水和用量,在线工作台只承担体验和调试。

开发者 API Key

生产调用使用控制台创建的租户 API Key。密钥只在创建时显示一次,请放在自己的服务端或本地环境变量。

本地或服务器调用

接入从 curl、SDK 或后端 HTTP 客户端开始。在线工作台不替代业务系统里的 API 调用。

统一账务

对话和视频任务共用余额、冻结、扣费、释放、流水和用量视图,按租户统一归因。

Quickstart

三步完成第一次 API 调用

上线前的最小闭环是:登录控制台创建 Key,读取当前租户可用模型,再从自己的运行环境调用接口。

01

创建 API Key

进入租户控制台的 API Key 页面创建密钥,明文只显示一次。

02

读取模型目录

调用 GET /v1/models 获取可用模型、协议和参考计费单位。

03

发起业务请求

按能力调用对话或视频接口,随后在控制台查看余额、流水和用量。

模型目录

按能力理解模型,按目录选择 ID

只展示平台能力、可用状态和参考计费单位。应用只需要知道当前租户可以调用什么、怎么计费、状态是否可用。

视频生成

面向文生视频、参考图生视频和长任务管理。用户选择规格,系统负责排队、冻结、扣费和结果追踪。

标准视频生成
已开放

默认档,适合日常创意短片、API 试跑和在线体验。

高质量视频生成
灰度

更高规格,用于灰度租户和重点任务。

参考图生视频
联调中

首帧/参考图资产先进入平台资产库,再提交任务。

大模型对话

按租户可用目录展示对话模型,统一支持模型选择、流式回复、token 用量和账单归因。

通用对话
已开放

面向写作、问答、总结和轻量分析。

推理与代码
已开放

面向复杂推理、代码生成和调试辅助。

高速低成本
已开放

面向高频请求、草稿和批量任务。

长上下文
可配置

面向长文档理解和多轮上下文任务。

开发者接入

以租户 API Key 为入口,模型目录、对话、视频任务、账单和用量共用同一套身份与余额。

模型目录
已开放

读取当前租户可用模型、协议能力和参考计费单位。

对话接口
已开放

兼容常见 chat completions 调用形态,支持流式输出。

视频任务接口
已开放

提交异步生成任务,随后轮询状态与产物链接。

账单与用量
已开放

查看余额、冻结、流水和模型维度聚合用量。

API 示例

从自己的运行环境发起请求

示例中的域名和模型 ID 以部署环境和模型目录返回值为准。不要把 API Key 写入浏览器端代码。

API 参考
鉴权
Authorization: Bearer <API_KEY>
模型目录
GET /v1/models
对话接口
POST /v1/chat/completions
视频提交
POST /v1/video/generations
任务查询
GET /v1/generations/{id}
账本流水
GET /v1/statements
用量聚合
GET /v1/usage?view=aggregate
环境变量与模型目录
export MODELGRID_API_KEY="mg_xxx"
export MODELGRID_API_BASE="https://api.xpkhub.com"

curl "$MODELGRID_API_BASE/v1/models" \
  -H "Authorization: Bearer $MODELGRID_API_KEY"
流式对话
curl https://api.xpkhub.com/v1/chat/completions \
  -H "Authorization: Bearer $MODELGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<CHAT_MODEL_ID>",
    "messages": [{"role": "user", "content": "你好,用一句话介绍 ModelGrid"}],
    "stream": true
  }'
Node.js 对话请求
const baseURL = process.env.MODELGRID_API_BASE ?? "https://api.xpkhub.com";

const response = await fetch(`${baseURL}/v1/chat/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MODELGRID_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "<CHAT_MODEL_ID>",
    messages: [{ role: "user", content: "用一句话介绍 ModelGrid" }],
    stream: false,
  }),
});

if (!response.ok) {
  throw new Error(`ModelGrid request failed: ${response.status} ${await response.text()}`);
}

console.log(await response.json());
视频任务提交
curl https://api.xpkhub.com/v1/video/generations \
  -H "Authorization: Bearer $MODELGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<VIDEO_MODEL_ID>",
    "prompt": "一辆白色概念车驶过干净的摄影棚地面",
    "duration_seconds": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'
Python 视频任务提交与轮询
import os
import time
import requests

base_url = os.getenv("MODELGRID_API_BASE", "https://api.xpkhub.com")
api_key = os.environ["MODELGRID_API_KEY"]

submit = requests.post(
    f"{base_url}/v1/video/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Idempotency-Key": "order-123-video-001",
    },
    json={
        "model": "<VIDEO_MODEL_ID>",
        "prompt": "一辆白色概念车驶过干净的摄影棚地面",
        "duration_seconds": 5,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["id"]

while True:
    task = requests.get(
        f"{base_url}/v1/generations/{task_id}",
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=30,
    )
    task.raise_for_status()
    data = task.json()
    print(data["status"], data.get("asset_urls"))
    if data["status"] in ("succeeded", "settled", "failed"):
        break
    time.sleep(5)
运行与排障

把长任务、幂等和错误处理放进业务代码

正式接入时,对话请求按同步/流式处理;视频生成按异步任务处理,提交后轮询状态并以最终流水为准。

Key 只进服务端

API Key 应放在环境变量、密钥管理或后端配置里。浏览器只使用你自己的业务会话,不要直连平台 API。

视频任务要可恢复

保存 task_id 和业务订单号。页面关闭、服务重启或网络抖动后,仍然可以继续查询任务状态和产物链接。

错误态要有动作

余额不足、参数错误、限流和平台异常应该走不同处理路径,不要统一提示生成失败。

常见错误与处理建议
状态码含义建议动作
401API Key 缺失、无效或已吊销重新创建 Key,确认只在服务端环境变量读取。
403租户、账号或模型能力未开放检查租户状态、模型可用状态和权限配置。
402余额不足或冻结额度不够充值后重试,或降低视频规格/请求规模。
404模型、任务或资源不存在先读取 /v1/models,任务查询只使用本租户创建的 task_id。
409幂等键冲突或重复操作同一业务请求复用 Idempotency-Key,不同请求使用新键。
422参数不合法或规格不支持按模型目录和接口文档修正 model、比例、时长、分辨率等参数。
429请求频率或并发超限退避重试,减少并发,必要时联系运营调整限额。
5xx平台或上游临时异常保留 request_id 和 task_id,稍后重试或提交排障。