从 API Key 开始接入模型能力
真实业务通常在本地脚本、后端服务或自有服务器调用 ModelGrid API。控制台用于创建 Key、查看余额、流水和用量,在线工作台只承担体验和调试。
开发者 API Key
生产调用使用控制台创建的租户 API Key。密钥只在创建时显示一次,请放在自己的服务端或本地环境变量。
本地或服务器调用
接入从 curl、SDK 或后端 HTTP 客户端开始。在线工作台不替代业务系统里的 API 调用。
统一账务
对话和视频任务共用余额、冻结、扣费、释放、流水和用量视图,按租户统一归因。
三步完成第一次 API 调用
上线前的最小闭环是:登录控制台创建 Key,读取当前租户可用模型,再从自己的运行环境调用接口。
创建 API Key
进入租户控制台的 API Key 页面创建密钥,明文只显示一次。
读取模型目录
调用 GET /v1/models 获取可用模型、协议和参考计费单位。
发起业务请求
按能力调用对话或视频接口,随后在控制台查看余额、流水和用量。
按能力理解模型,按目录选择 ID
只展示平台能力、可用状态和参考计费单位。应用只需要知道当前租户可以调用什么、怎么计费、状态是否可用。
视频生成
面向文生视频、参考图生视频和长任务管理。用户选择规格,系统负责排队、冻结、扣费和结果追踪。
默认档,适合日常创意短片、API 试跑和在线体验。
更高规格,用于灰度租户和重点任务。
首帧/参考图资产先进入平台资产库,再提交任务。
大模型对话
按租户可用目录展示对话模型,统一支持模型选择、流式回复、token 用量和账单归因。
面向写作、问答、总结和轻量分析。
面向复杂推理、代码生成和调试辅助。
面向高频请求、草稿和批量任务。
面向长文档理解和多轮上下文任务。
开发者接入
以租户 API Key 为入口,模型目录、对话、视频任务、账单和用量共用同一套身份与余额。
读取当前租户可用模型、协议能力和参考计费单位。
兼容常见 chat completions 调用形态,支持流式输出。
提交异步生成任务,随后轮询状态与产物链接。
查看余额、冻结、流水和模型维度聚合用量。
从自己的运行环境发起请求
示例中的域名和模型 ID 以部署环境和模型目录返回值为准。不要把 API Key 写入浏览器端代码。
Authorization: Bearer <API_KEY>GET /v1/modelsPOST /v1/chat/completionsPOST /v1/video/generationsGET /v1/generations/{id}GET /v1/statementsGET /v1/usage?view=aggregateexport 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
}'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"
}'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 和业务订单号。页面关闭、服务重启或网络抖动后,仍然可以继续查询任务状态和产物链接。
错误态要有动作
余额不足、参数错误、限流和平台异常应该走不同处理路径,不要统一提示生成失败。
| 状态码 | 含义 | 建议动作 |
|---|---|---|
| 401 | API Key 缺失、无效或已吊销 | 重新创建 Key,确认只在服务端环境变量读取。 |
| 403 | 租户、账号或模型能力未开放 | 检查租户状态、模型可用状态和权限配置。 |
| 402 | 余额不足或冻结额度不够 | 充值后重试,或降低视频规格/请求规模。 |
| 404 | 模型、任务或资源不存在 | 先读取 /v1/models,任务查询只使用本租户创建的 task_id。 |
| 409 | 幂等键冲突或重复操作 | 同一业务请求复用 Idempotency-Key,不同请求使用新键。 |
| 422 | 参数不合法或规格不支持 | 按模型目录和接口文档修正 model、比例、时长、分辨率等参数。 |
| 429 | 请求频率或并发超限 | 退避重试,减少并发,必要时联系运营调整限额。 |
| 5xx | 平台或上游临时异常 | 保留 request_id 和 task_id,稍后重试或提交排障。 |