开放 API 文档

GPNK 支持第三方通过本站 API 接入实时换人能力。你拿到的是本站 Key,不会接触上游主密钥。

Base URL
https://lchy.cocmc.cn

版本前缀:/api/v1 · 模型:Xmax X2.1 实时

概述

典型接入流程:

  1. 在前台 /apikeys 或后台「开放 API 密钥」创建 Key(前缀 lsk_)
  2. 调用 POST /api/v1/token 获取临时凭证
  3. (可选)调用 POST /api/v1/upload 上传参考图,或使用 GET /api/v1/accessories 预设图
  4. 客户端用官方 SDK + 临时 Key 开摄像头实时生成(模型 x2.1)
  5. 结束后调用 POST /api/v1/session-end 释放会话

可视化示例也可在模型页切换到「API」查看:/model

可用模型

模型状态说明
x2.1当前推荐最新实时交互视频模型,更高画质
x2.0兼容上一代模型,特殊场景可指定

操作模式

通过提示词 + 参考图组合实现不同能力(人物配饰分类与之对应):

模式分类默认提示词示例
CharXrole视频中人物替换成参考图中角色
ClothXcloth视频中人物衣服替换成参考图中衣服
VibeXstyle视频风格变为参考图指定的风格
DimX / Freefree自定义提示词,保持主体增减细节
Summonsummon召唤参考图中的角色到视频人物身边

鉴权

所有业务接口(除健康检查)需携带 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_secondsint可选,不能超过该 Key 配置上限
points_limitint可选,积分上限
session_limitint可选,并发会话上限
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-end
curl -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

  1. 业务后端调用 POST /api/v1/token(以及可选 /upload、/accessories)
  2. 客户端使用各端 Xmax 官方 SDK,配置 apiKey=temporaryApiKey、model=x2.1
  3. 会话结束由后端或客户端回调 POST /api/v1/session-end

模型页「API」Tab 提供可切换平台的示例代码与参数表:/model

错误码

HTTP含义
401缺少 / 无效 API Key
403能力未启用
429触发每分钟限流
400参数错误
502 / 503上游异常或服务端未配置模型主 Key
运营提示

后台路径:系统管理 → 开放 API 密钥;上游 Xmax 主 Key 在「系统设置 → API 配置」。人物配饰在「人物配饰」菜单维护。