@xmaxai/sdk

面向 Xmax Open Platform 的浏览器端 SDK。公开 API 以 headless Realtime 客户端（createXmaxClient）为主：负责 session 生命周期、火山 RTC 进房推流、远端渲染绑定，以及 start/stop 信令。

本包以浏览器环境为主要运行场景（依赖 fetch / AbortController / File / DOM / HTMLCanvasElement.captureStream）。

SDK 不包含 UI（参考图选择器、prompt 输入框、视频布局等由宿主应用自行实现）。

安装

本 SDK 按接入区域发布为两个包，API 完全一致，仅内置的默认接口地址不同：

| 包名 | 区域 | 默认接口 | |------|------|----------| | @xmaxai/sdk | 国内 | https://cloud.xmax.22duck.cn/open/api/v1 | | @xmaxai/sdk-global | 海外 | https://api.xmax.cloud/open/api/v1 |

# 国内
npm install @xmaxai/sdk
# 海外
npm install @xmaxai/sdk-global

两个包由同一套源码构建（构建时通过 XMAX_SDK_REGION 注入默认地址），无需维护两份代码。任意包都可通过 baseUrl 显式覆盖默认地址。

包入口

| 入口 | 说明 | |------|------| | @xmaxai/sdk | 推荐 — createXmaxClient、models，以及 HTTP Client / RTC 底层 API | | @xmaxai/sdk/react | React bindings（可选） |

快速开始

与平台 Playground 相同的调用方式：获取摄像头 → createXmaxClient → connect，通过 initialState 传入 prompt 和 参考图 URL。

baseUrl 已内置生产环境默认值，一般无需传入；仅在 staging / 私有部署时覆盖。

import { createXmaxClient, models } from "@xmaxai/sdk";

const model = models.realtime("x2.0");

const stream = await navigator.mediaDevices.getUserMedia({
  video: {
    frameRate: model.fps,
    width: model.width,
    height: model.height,
  },
});

const client = createXmaxClient({
  apiKey: "<YOUR_XMAX_API_KEY>",
});

const localElement = document.querySelector("#video-input") as HTMLElement;
const remoteElement = document.querySelector("#video-output") as HTMLElement;

const realtimeClient = await client.realtime.connect(stream, {
  model,
  localElement,
  remoteElement,
  mirror: "auto",
  initialState: {
    prompt: { text: "<YOUR_PROMPT>" },
    image: "<YOUR_REF_IMAGE_URL>",
    autoStart: true,
  },
});

await realtimeClient.setPrompt("<YOUR_PROMPT>");

await realtimeClient.setRefImage("<YOUR_REF_IMAGE_URL>");
await realtimeClient.restart();

await realtimeClient.stop();
await realtimeClient.disconnect();

上传参考图并健康检查（可选）

与 Playground 加参考图相同：先 COS 上传，再 POST /cos/image/check。
现有 client.files.uploadImage 只上传、不做检查；需要检查时：

const url = await client.files.uploadAndCheckImage(file);
await realtimeClient.set({ image: url });

流程说明

• createXmaxClient({ apiKey }) 即可，baseUrl 默认指向官方生产 Open API。
• connect() 自动完成：createSession → heartbeat → join RTC → 推流 →（autoStart: true 时）发送 start。
• initialState.prompt 传 { text: string }；initialState.image 传参考图 URL。
• 宿主自行提供 #video-input / #video-output 容器元素。
• API/RTC 错误通过 onError 回调交给调用方处理。在 createXmaxClient 或 connect 任一处传入即可（connect 优先）。
• onDisconnect 仅在 session 成功建立后断开时触发；connect() 失败不会回调。

自定义 baseUrl（可选）

import {
  createXmaxClient,
  XMAX_OPEN_API_PRODUCTION_BASE_URL,
} from "@xmaxai/sdk";

const client = createXmaxClient({
  apiKey: "<YOUR_XMAX_API_KEY>",
  baseUrl: XMAX_OPEN_API_PRODUCTION_BASE_URL, // 或自定义前缀，如 https://your-host/open/api/v1
});

API 参考

createXmaxClient

createXmaxClient({
  apiKey: string,           // 必填
  baseUrl?: string,         // 可选，默认内置生产环境地址
  authToken?: string,
  heartbeatIntervalMs?: number,
  onError?: (message, error?) => void,
  onLog?: (entry) => void,
})

client.realtime.connect

client.realtime.connect(stream, {
  model: RealtimeModel,     // models.realtime("x2.0")
  localElement?: HTMLElement,
  remoteElement?: HTMLElement,
  onRemoteStream?: (stream: MediaStream) => void,
  onError?: (message, error?) => void,  // optional; overrides createXmaxClient.onError
  onDisconnect?: (reason) => void,      // "client" | "session_inactive" | "heartbeat_error"
  mirror?: "auto" | boolean,
  initialState?: {
    prompt?: string | { text: string },
    image?: string,
    autoStart?: boolean,
  },
  size?: [number, number],
  mobile?: boolean,
})

When remoteElement is provided, drag is enabled by default after generation starts. Pass drag: false to disable.

RealtimeSession 主要方法

| 方法 | 说明 | |------|------| | setPrompt(prompt) | 更新 prompt 并重新生成 | | setRefImage(url \| File) | 设置参考图 | | restart(options?) | 用当前 prompt / 参考图重新生成 | | sendTracks(tracks) | 发送拖拽轨迹（通常由内置 drag 自动调用） | | stop() | 停止当前生成 | | disconnect() | 断开 session 并离开 RTC |

安全建议

• apiKey / authToken 属于敏感信息，避免写入前端日志。
• 生产环境建议通过后端签发短期令牌或 API 代理，避免在浏览器暴露高权限密钥。
• COS STS 临时密钥会在上传期间存在于浏览器内存，请确保 STS 权限最小化。

依赖说明

| 依赖 | 用途 | |------|------| | @volcengine/rtc | 火山引擎 Web RTC | | cos-js-sdk-v5 | 腾讯云 COS 直传 |

开发与构建

pnpm -C packages/open-sdk install
pnpm -C packages/open-sdk test
pnpm -C packages/open-sdk build          # 默认按国内(cn)地址构建
pnpm -C packages/open-sdk typecheck

双区域构建 / 发布

一套源码 → 两个 npm 包。区域通过环境变量 XMAX_SDK_REGION（cn | global）在构建时注入。

# 仅构建
pnpm -C packages/open-sdk run build:cn        # → 国内默认地址
pnpm -C packages/open-sdk run build:global    # → 海外默认地址

# 发布（会自动切换包名 + 以对应区域重新构建测试）
pnpm -C packages/open-sdk run publish:cn      # 发布 @xmaxai/sdk
pnpm -C packages/open-sdk run publish:global  # 发布 @xmaxai/sdk-global
pnpm -C packages/open-sdk run publish:all     # 两个都发

# 透传 npm 参数，例如预演 / 打 tag
node packages/open-sdk/scripts/publish-sdk.mjs global --dry-run

publish-sdk.mjs 会临时改写 package.json 的 name 后调用 npm publish，发布结束（含失败）都会还原为默认名。package.json 中 publishConfig.provenance 需在带 OIDC 的 CI 环境才生效，本地发布如报 provenance 相关错误可临时关闭。

变更记录

见 CHANGELOG.md。

License

MIT