开放 API 文档
GPNK 支持第三方通过本站 API 接入实时换人能力。你拿到的是本站 Key,不会接触上游主密钥。
Base URL
https://lchy.cocmc.cn
版本前缀:/api/v1 · 模型:Xmax X2.1 实时
概述
典型接入流程:
- 在前台 /apikeys 或后台「开放 API 密钥」创建 Key(前缀
lsk_) - 调用
POST /api/v1/token获取临时凭证 - (可选)调用
POST /api/v1/upload上传参考图,或使用GET /api/v1/accessories预设图 - 客户端用官方 SDK + 临时 Key 开摄像头实时生成(模型
x2.1) - 结束后调用
POST /api/v1/session-end释放会话
可视化示例也可在模型页切换到「API」查看:/model
可用模型
| 模型 | 状态 | 说明 |
|---|---|---|
x2.1 | 当前推荐 | 最新实时交互视频模型,更高画质 |
x2.0 | 兼容 | 上一代模型,特殊场景可指定 |
操作模式
通过提示词 + 参考图组合实现不同能力(人物配饰分类与之对应):
| 模式 | 分类 | 默认提示词示例 |
|---|---|---|
| CharX | role | 视频中人物替换成参考图中角色 |
| ClothX | cloth | 视频中人物衣服替换成参考图中衣服 |
| VibeX | style | 视频风格变为参考图指定的风格 |
| DimX / Free | free | 自定义提示词,保持主体增减细节 |
| Summon | summon | 召唤参考图中的角色到视频人物身边 |
鉴权
所有业务接口(除健康检查)需携带 API Key(两种均可):
- 用户个人 Key(登录后自动生成,可在
/apikeys管理) - 后台「开放 API 密钥」发放给第三方的平台 Key
X-Api-Key: lsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
或:
Authorization: Bearer lsk_xxxxxxxx...
也支持在 JSON / 表单里传 api_key(不推荐,易泄露到日志)。
健康检查
GET
/api/v1/health · 无需鉴权curl -s https://lchy.cocmc.cn/api/v1/health
{
"success": true,
"service": "GPNK",
"version": "v2.1",
"time": "2026-11-10T16:00:00+08:00"
}
人物配饰列表
GET
/api/v1/accessories可选查询参数 category:role / cloth / style / free / summon
curl -s "https://lchy.cocmc.cn/api/v1/accessories?category=role" \ -H "X-Api-Key: lsk_xxx"
{
"success": true,
"total": 19,
"data": [
{
"code": "role-xxxx",
"category": "role",
"category_label": "换角色",
"name": "硅谷马哥",
"prompt": "视频中人物替换成参考图中角色",
"thumb": "https://your.domain/Storage/accessories/role/xxx.jpeg",
"sort_order": 0
}
]
}
创建临时凭证
POST
/api/v1/token返回的 temporaryApiKey 仅用于前端 SDK 连接实时模型,有时效与积分上限。
| 字段 | 类型 | 说明 |
|---|---|---|
| expire_seconds | int | 可选,不能超过该 Key 配置上限 |
| points_limit | int | 可选,积分上限 |
| session_limit | int | 可选,并发会话上限 |
curl -s -X POST https://lchy.cocmc.cn/api/v1/token \
-H "Content-Type: application/json" \
-H "X-Api-Key: lsk_xxx" \
-d '{"expire_seconds":3600,"points_limit":600}'
{
"success": true,
"data": {
"temporaryApiKey": "tmp_xxx",
"expireTimestamp": 1731240000,
"environment": "china",
"sessionId": 12,
"pointsLimit": 600,
"defaultPrompt": "视频中角色替换成参考图中角色",
"sdk": {
"npm": "@xmaxai/web-sdk",
"cdn": "/Static/vendor/xmax/web-sdk.bundle.js?v=1",
"model": "x2.1"
}
}
}
上传参考图
POST
/api/v1/upload · multipart/form-data字段名:file,支持 JPG / PNG / WEBP,最大 10MB。
curl -s -X POST https://lchy.cocmc.cn/api/v1/upload \ -H "X-Api-Key: lsk_xxx" \ -F "file=@./ref.png"
{
"success": true,
"data": {
"url": "https://your.domain/Storage/open-api/20261110_xxxx.png",
"path": "/Storage/open-api/20261110_xxxx.png"
}
}
结束会话
POST
/api/v1/session-endcurl -s -X POST https://lchy.cocmc.cn/api/v1/session-end \
-H "Content-Type: application/json" \
-H "X-Api-Key: lsk_xxx" \
-d '{"session_id":12,"duration_seconds":120,"temporary_api_key":"tmp_xxx"}'
多端接入示例
Web(浏览器官方 SDK)
<script type="module">
import {
XmaxClient, XmaxConfiguration, XmaxEnvironment, RealtimeModel,
RealtimeConfiguration, RealtimeContext, RealtimeCameraPreset,
CameraPosition, XmaxRealtimeDualVideoView
} from '/Static/vendor/xmax/web-sdk.bundle.js?v=1';
const tokenRes = await fetch('https://lchy.cocmc.cn/api/v1/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Api-Key': 'lsk_xxx' },
body: JSON.stringify({ expire_seconds: 3600, points_limit: 600 })
}).then(r => r.json());
const { temporaryApiKey, environment, defaultPrompt } = tokenRes.data;
const env = environment === 'global' ? XmaxEnvironment.global : XmaxEnvironment.china;
const client = new XmaxClient(new XmaxConfiguration({ apiKey: temporaryApiKey, environment: env }));
const realtime = client.createRealtimeManager(new RealtimeConfiguration({ model: RealtimeModel.x2_1 }));
const view = new XmaxRealtimeDualVideoView();
view.attach(document.getElementById('mount'));
const localStream = await realtime.createLocalCameraStream({
preset: RealtimeCameraPreset.resolution1920x1080,
position: CameraPosition.front,
useMicrophone: false,
});
view.localTrack = localStream.videoTrack;
const remote = await realtime.startGeneration({
localStream,
context: new RealtimeContext({
prompt: defaultPrompt,
referencePath: 'https://your.cdn/ref.png',
}),
});
view.remoteTrack = remote.videoTrack;
</script>
Node.js / Python(服务端换票)
移动端 / Unity 等场景建议由你的业务后端调用本站 Open API,把 temporaryApiKey 下发给客户端,再接各端官方 SDK。
// Node.js
const res = await fetch('https://lchy.cocmc.cn/api/v1/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Api-Key': 'lsk_xxx' },
body: JSON.stringify({ expire_seconds: 3600, points_limit: 600 })
});
const { data } = await res.json();
// data.temporaryApiKey 下发给 App / Unity
# Python
import requests
r = requests.post(
"https://lchy.cocmc.cn/api/v1/token",
headers={"X-Api-Key": "lsk_xxx", "Content-Type": "application/json"},
json={"expire_seconds": 3600, "points_limit": 600},
)
print(r.json())
iOS / Android / HarmonyOS / Flutter / React Native / Unity
- 业务后端调用
POST /api/v1/token(以及可选/upload、/accessories) - 客户端使用各端 Xmax 官方 SDK,配置
apiKey=temporaryApiKey、model=x2.1 - 会话结束由后端或客户端回调
POST /api/v1/session-end
模型页「API」Tab 提供可切换平台的示例代码与参数表:/model
错误码
| HTTP | 含义 |
|---|---|
| 401 | 缺少 / 无效 API Key |
| 403 | 能力未启用 |
| 429 | 触发每分钟限流 |
| 400 | 参数错误 |
| 502 / 503 | 上游异常或服务端未配置模型主 Key |
运营提示
后台路径:系统管理 → 开放 API 密钥;上游 Xmax 主 Key 在「系统设置 → API 配置」。人物配饰在「人物配饰」菜单维护。