@xmaxai/web-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,888 @@
+import { R as RealtimeVideoFormat, a as RealtimeVideoTrack, C as CameraPosition, V as VideoContentMode } from './VideoContentMode-BXkqM4XG.js';
+export { b as RealtimeVideoEncoderPreference, c as RealtimeVideoFormatInit } from './VideoContentMode-BXkqM4XG.js';
+
+/**
+ * SDK 当前支持的实时生成模型。
+ */
+declare enum RealtimeModel {
+    /** Xmax X2 Fast 1080P 实时生成模型。 */
+    x2_fast_1080p = "x2-fast-1080p"
+}
+interface ModelSize {
+    width: number;
+    height: number;
+}
+/** 未指定视频规格时，各媒体来源使用的默认帧率。 */
+declare function defaultFrameRate(_model: RealtimeModel): number;
+/** 摄像头采集使用的默认视频规格。 */
+declare function defaultCameraVideoFormat(_model: RealtimeModel): RealtimeVideoFormat;
+
+/**
+ * 定义媒体输入规则与平台媒体能力查询能力。
+ */
+interface MediaServicing {
+    /** 校验并保留原始尺寸；Web 插帧不降低回传分辨率。 */
+    resolveFrameInterpolationSize(size: ModelSize): ModelSize;
+    supportsFrameInterpolation(size: ModelSize): Promise<boolean>;
+    /**
+     * 按模型输入规则解析目标尺寸。
+     *
+     * 分辨率桶非空时必须精确匹配；否则按像素面积上下限等比缩放并对齐到
+     * 模型要求的像素倍数。
+     *
+     * @throws 尺寸无效或不满足模型约束时抛出错误。
+     */
+    resolveModelInputSize(size: ModelSize): ModelSize;
+}
+
+/**
+ * 上传完成后返回的已存储文件信息。
+ */
+declare class StoredFile {
+    /** 文件的访问地址。 */
+    readonly url: string;
+    /** 对象存储中的对象键。 */
+    readonly objectKey: string;
+    /** 对象存储返回的 ETag；未返回时为空。 */
+    readonly etag?: string;
+    /**
+     * 创建已存储文件信息。
+     *
+     * @param init.url 文件访问地址。
+     * @param init.objectKey 对象键。
+     * @param init.etag 对象存储返回的 ETag。
+     */
+    constructor(init: {
+        url: string;
+        objectKey: string;
+        etag?: string;
+    });
+}
+
+/** 上传图片的参数。 */
+interface StorageUploadOptions {
+    /** 图片数据。 */
+    data: Blob | ArrayBuffer | Uint8Array;
+    /** 文件名；用于对象键后缀和缺省内容类型推断。 */
+    fileName: string;
+    /** 图片 MIME 类型；缺省按文件名后缀推断。 */
+    contentType?: string;
+    /** 上传进度回调（已传字节数、总字节数）。 */
+    onProgress?: (transferred: number, total: number) => void;
+}
+/**
+ * 定义文件存储能力：上传图片到对象存储并返回访问地址。
+ */
+interface StorageServicing {
+    /**
+     * 上传图片。
+     *
+     * 从 Xmax 服务获取临时凭证后直传对象存储，返回的地址可用作
+     * 实时生成的参考图路径。
+     *
+     * @returns 已存储文件信息。
+     * @throws 参数无效、凭证获取失败或上传失败时抛出错误。
+     */
+    uploadImage(options: StorageUploadOptions): Promise<StoredFile>;
+}
+
+interface FrameInterpolationConfiguration {
+    /** 是否请求开启远端插帧，默认 true。不支持时自动播放原视频。 */
+    enabled?: boolean;
+    /** 显示帧率上限，默认 60；每对源帧最多插入一帧。取值 1–60。 */
+    targetFrameRate?: number;
+}
+interface RealtimeConfigurationInit {
+    /** 实时生成业务使用的模型。 */
+    model: RealtimeModel;
+    /**
+     * 是否默认开启远端生成画面的插帧。
+     * frameInterpolation.enabled 显式设置时优先。
+     */
+    isFrameInterpolationEnabled?: boolean;
+    frameInterpolation?: FrameInterpolationConfiguration;
+}
+/**
+ * 创建实时 Manager 所需的业务配置。
+ */
+declare class RealtimeConfiguration {
+    /** 实时生成业务使用的模型。 */
+    readonly model: RealtimeModel;
+    /** 是否默认请求开启远端生成画面的插帧。 */
+    readonly isFrameInterpolationEnabled: boolean;
+    readonly frameInterpolation: Readonly<Required<FrameInterpolationConfiguration>>;
+    /**
+     * 创建实时业务配置。
+     *
+     * @param init.model 实时生成业务使用的模型。
+     * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧。
+     */
+    constructor(init: RealtimeConfigurationInit);
+}
+
+/** TRTC 网络质量等级：未知、极好、良好、一般、差、极差、断网。 */
+type NetworkQualityLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** 本端 RTC 连接的网络统计，不依赖远端生成流是否已经到达。 */
+interface NetworkStatistics {
+    readonly uplinkQuality?: NetworkQualityLevel;
+    /** 所有下行连接的平均网络质量。 */
+    readonly downlinkQuality?: NetworkQualityLevel;
+    /** 上行连接到 TRTC 云端的往返延迟，单位 ms，不是单程延迟。 */
+    readonly uplinkRttMs?: number;
+    /** 所有下行连接到 TRTC 云端的平均往返延迟，单位 ms。 */
+    readonly downlinkRttMs?: number;
+}
+/** undefined 表示尚无采样或连接已清理。 */
+type NetworkStatisticsListener = (statistics: NetworkStatistics | undefined) => void;
+
+interface RealtimeContextInit {
+    /** 实时生成使用的文本条件。 */
+    prompt: string;
+    /** 已上传参考图片的可选远端路径。 */
+    referencePath?: string;
+}
+/**
+ * 单次实时生成任务的文本和参考资源上下文。
+ */
+declare class RealtimeContext {
+    /** 实时生成使用的文本条件。 */
+    readonly prompt: string;
+    /** 已上传参考图片的可选远端路径。 */
+    readonly referencePath?: string;
+    /** 创建实时生成条件并规范化文本和参考路径。 */
+    constructor(init: RealtimeContextInit);
+}
+
+/**
+ * 实时生成输入/输出的媒体流。
+ */
+declare class RealtimeMediaStream {
+    /** 媒体流标识。 */
+    readonly id: string;
+    /** 媒体流包含的视频轨道。 */
+    readonly videoTrack?: RealtimeVideoTrack;
+    /**
+     * 创建实时媒体流。
+     *
+     * @param init.id 媒体流标识。
+     * @param init.videoTrack 媒体流包含的视频轨道。
+     */
+    constructor(init: {
+        id: string;
+        videoTrack?: RealtimeVideoTrack;
+    });
+}
+
+/**
+ * SDK 向接入方暴露的统一错误码。
+ */
+declare enum XmaxErrorCode {
+    /** API Key 未配置或为空。 */
+    invalidAPIKey = "INVALID_API_KEY",
+    /** 调用参数、配置或当前生命周期状态不符合操作要求。 */
+    invalidConfiguration = "INVALID_CONFIGURATION",
+    /** SDK 内部发生无法归类的非预期错误。 */
+    internalError = "INTERNAL_ERROR",
+    /** 网络不可用、连接失败或 HTTP 请求无法完成。 */
+    networkError = "NETWORK_ERROR",
+    /** Xmax API 返回业务失败，或者响应数据无法正确解析。 */
+    apiError = "API_ERROR",
+    /** 实时生成会话数据缺失、会话关闭或心跳状态异常。 */
+    sessionError = "SESSION_ERROR",
+    /** RTC Engine、房间、媒体传输或渲染绑定发生错误。 */
+    rtcError = "RTC_ERROR",
+    /** 本地媒体读取、解码、同步或帧处理发生错误。 */
+    mediaError = "MEDIA_ERROR",
+    /** 当前系统、设备或视频规格不支持远端视频插帧。 */
+    frameInterpolationUnsupported = "FRAME_INTERPOLATION_UNSUPPORTED",
+    /** 接入方未授予相机权限。 */
+    cameraPermissionDenied = "CAMERA_PERMISSION_DENIED",
+    /** 启动相机在限定时间内未获得足够明亮且稳定的画面，未发布视频。 */
+    cameraExposureTimeout = "CAMERA_EXPOSURE_TIMEOUT",
+    /** 接入方未授予麦克风权限。 */
+    microphonePermissionDenied = "MICROPHONE_PERMISSION_DENIED",
+    /** 文件或二进制数据上传失败。 */
+    uploadError = "UPLOAD_ERROR",
+    /** 远端文件下载失败。 */
+    downloadError = "DOWNLOAD_ERROR",
+    /** 图片未通过内容安全检查。 */
+    unsafeImage = "UNSAFE_IMAGE",
+    /** 操作因生命周期切换或接入方主动终止而正常取消。 */
+    cancelled = "CANCELLED",
+    /** 等待连接、房间事件或生成结果超过规定时间。 */
+    timeout = "TIMEOUT"
+}
+/** SDK 内部组件上报统一错误时使用的监听器。 */
+type XmaxErrorListener = (error: XmaxError) => void;
+/**
+ * 表示 SDK 抛出或回调给接入方的统一错误。
+ */
+declare class XmaxError extends Error {
+    /** SDK 统一错误码。 */
+    readonly code: XmaxErrorCode;
+    /** Xmax API 返回的业务错误码；非 API 业务错误时为空。 */
+    readonly apiCode?: number;
+    /** HTTP 响应状态码；请求未获得响应时为空。 */
+    readonly httpStatus?: number;
+    /**
+     * 创建 SDK 错误。
+     *
+     * @param code SDK 统一错误码。
+     * @param message 面向接入方的可读错误说明。
+     * @param options Xmax API 业务错误码与 HTTP 状态码（可选）。
+     */
+    constructor(code: XmaxErrorCode, message: string, options?: {
+        apiCode?: number;
+        httpStatus?: number;
+    });
+    /**
+     * 将未知错误转换为 SDK 内部错误，已有 `XmaxError` 原样返回。
+     *
+     * @param error 待转换的错误。
+     * @returns 可向接入方抛出或回调的统一错误。
+     */
+    static from(error: unknown): XmaxError;
+}
+
+/**
+ * 实时业务连接状态。
+ */
+declare enum RealtimeConnectionState {
+    /** 没有可用的本地媒体流。 */
+    idle = "Idle",
+    /** 正在准备本地媒体流；摄像头还需等待有效帧和预览视图绑定。 */
+    preparing = "Preparing",
+    /** 本地媒体流已就绪，可以预览、连接和生成。 */
+    ready = "Ready",
+    /** 正在创建 Session、加入 Room 并发布本地流。 */
+    connecting = "Connecting",
+    /** 实时连接已建立，当前没有生成任务。 */
+    connected = "Connected",
+    /** 实时连接已建立且生成任务正在运行。 */
+    generating = "Generating",
+    /** 正在清理生成、Room 和 Session 资源。 */
+    disconnecting = "Disconnecting"
+}
+/**
+ * 进入当前实时状态的原因。
+ */
+type RealtimeReason = {
+    kind: "normal";
+} | {
+    kind: "orientationChanged";
+} | {
+    kind: "failure";
+    error: XmaxError;
+};
+declare const RealtimeReason: {
+    normal: RealtimeReason;
+    orientationChanged: RealtimeReason;
+    failure(error: XmaxError): RealtimeReason;
+};
+interface RealtimeStateInit {
+    connectionState: RealtimeConnectionState;
+    sessionID?: string;
+    taskID?: string;
+    reason?: RealtimeReason;
+}
+/**
+ * 实时业务当前状态快照。
+ */
+declare class RealtimeState {
+    /** 当前连接生命周期状态。 */
+    readonly connectionState: RealtimeConnectionState;
+    /** 当前或最近一次实时 Session 标识。 */
+    readonly sessionID?: string;
+    /** 当前生成任务标识。 */
+    readonly taskID?: string;
+    /** 进入当前状态的原因；正常开始新的操作时清空。 */
+    readonly reason?: RealtimeReason;
+    /**
+     * 创建实时状态快照。
+     *
+     * @param init.connectionState 当前连接生命周期状态。
+     * @param init.sessionID 当前或最近一次实时 Session 标识。
+     * @param init.taskID 当前生成任务标识。
+     * @param init.reason 状态变化原因，默认无。
+     */
+    constructor(init: RealtimeStateInit);
+    /**
+     * 判断当前状态与另一状态是否等价：连接状态、会话、任务与原因种类一致。
+     *
+     * @param other 待比较的状态。
+     */
+    equals(other: RealtimeState): boolean;
+}
+/** 实时状态监听器。 */
+type RealtimeStateListener = (state: RealtimeState) => void;
+
+/**
+ * 一次相机启动的耗时快照，单位为毫秒；undefined 表示该阶段尚未完成。
+ * 新一轮打开摄像头时重置；失败、关闭或断开后保留已完成的值。
+ * 仅预览时不产生首帧和总耗时；预览后手动启动生成的等待计入总耗时。
+ */
+interface RealtimeLaunchTiming {
+    /** 开始打开摄像头到相机流创建完成（包含权限等待）。 */
+    readonly cameraMs?: number;
+    /** 开始创建会话到 RTC 进房并发布本地流完成。 */
+    readonly connectionMs?: number;
+    /** 开始发送生成信令到 SDK 远端视图首次呈现视频帧。 */
+    readonly firstFrameMs?: number;
+    /** 开始打开摄像头到 SDK 远端视图首次呈现视频帧。 */
+    readonly totalMs?: number;
+}
+/** 阶段完成时提供完整快照；不支持帧回调的浏览器以 playing 近似首帧。 */
+type RealtimeLaunchTimingListener = (timing: RealtimeLaunchTiming) => void;
+
+/** 视频流实际运行统计；缺失或无效指标为 undefined。 */
+interface VideoStatistics {
+    readonly width?: number;
+    readonly height?: number;
+    /** 实际帧率，单位 fps。 */
+    readonly frameRate?: number;
+    /** 实际码率，单位 kbps。 */
+    readonly bitrateKbps?: number;
+}
+/** undefined 表示当前没有可用统计（尚未发布、断开或停止）。 */
+type VideoStatisticsListener = (statistics: VideoStatistics | undefined) => void;
+/** 一路远端主视频流的接收统计。 */
+interface RemoteVideoStatistics extends VideoStatistics {
+    readonly userID: string;
+    /** 本端 SDK 到 TRTC 云端的往返延迟，单位 ms；不是与远端用户之间的 RTT。 */
+    readonly rttMs?: number;
+    /** 本端 SDK 到 TRTC 云端的上行丢包率，单位 %，不是结果流的发送端丢包率。 */
+    readonly uplinkLossPercent?: number;
+    /** TRTC 云端到本端 SDK 的下行丢包率，单位 %。 */
+    readonly downlinkLossPercent?: number;
+    /** 当前远端视频流的播放缓冲延迟，单位 ms。 */
+    readonly jitterBufferDelayMs?: number;
+    /** TRTC 媒体端到端延迟估算值，单位 ms；不代表完整 AI 处理链路耗时。 */
+    readonly endToEndDelayMs?: number;
+}
+/** undefined 表示当前结果流没有统计或已被清理。 */
+type RemoteVideoStatisticsListener = (statistics: RemoteVideoStatistics | undefined) => void;
+
+/**
+ * 定义 SDK 对接入方提供的实时媒体与生成控制能力。
+ */
+interface XmaxRealtimeManaging {
+    /** 实时能力配置。 */
+    readonly options: RealtimeConfiguration;
+    /** 当前实时连接与生成状态。 */
+    readonly currentState: RealtimeState;
+    /** 插帧功能开关；不随首帧等待、跳帧或视图挂载变化，不支持或故障降级时关闭。 */
+    readonly isFrameInterpolationEnabled: boolean;
+    /** 切换客户端插帧，不改变回传分辨率或重启任务。不支持时抛错且保留配置。 */
+    setFrameInterpolationEnabled(enabled: boolean): Promise<void>;
+    /** 当前本地媒体预览音量，取值范围为 `0...1`。 */
+    readonly localAudioVolume: number;
+    /** 当前远端生成音频播放音量，取值范围为 `0...1`。 */
+    readonly remoteAudioVolume: number;
+    /**
+     * 设置实时状态监听器。
+     * @param listener 实时状态回调；传入 `undefined` 时清除监听器。
+     */
+    setStateListener(listener?: RealtimeStateListener): Promise<void>;
+    /**
+     * 监听 TRTC 上下行网络质量和 RTT；立即回放最新快照，断开后回调 undefined。
+     * 独立于日志和远端生成流；传入 undefined 取消监听，监听器异常不影响主流程。
+     */
+    setNetworkStatisticsListener(listener?: NetworkStatisticsListener): Promise<void>;
+    /**
+     * 监听启动耗时；立即回放当前快照，每完成一个阶段再次回调。
+     * 新一轮打开摄像头时重置；失败或终止后冻结，更新生成条件不重置。
+     * 首帧统计需要将远端轨道绑定到 SDK 视频视图，且不会阻塞 startGeneration。
+     * 传入 undefined 清除监听器；监听器异常不影响生成流程。
+     */
+    setLaunchTimingListener(listener?: RealtimeLaunchTimingListener): Promise<void>;
+    /**
+     * 监听本地主视频流实际分辨率、帧率及码率（kbps），独立于日志开关。
+     * 设置后立即回放最新快照；未取得数据或停止/断开时回调 undefined。
+     * 传入 undefined 取消监听；监听器异常不影响生成流程。
+     */
+    setLocalVideoStatisticsListener(listener?: VideoStatisticsListener): Promise<void>;
+    /**
+     * 监听当前生成结果流的分辨率、帧率、码率、云端 RTT 和媒体 E2E 估算值。
+     * 独立于日志开关；立即回放最新快照，流消失或断开时回调 undefined。
+     * 传入 undefined 取消监听；监听器异常不影响生成流程。
+     */
+    setRemoteVideoStatisticsListener(listener?: RemoteVideoStatisticsListener): Promise<void>;
+    /**
+     * 设置本地媒体预览音量。
+     * @throws 音量超出有效范围时抛出错误。
+     */
+    setLocalAudioVolume(volume: number): Promise<void>;
+    /**
+     * 设置远端生成音频播放音量。
+     * 尚未连接或订阅远端流时保存配置，并在远端音频开始播放前应用。
+     * @throws 音量超出有效范围或 RTC 音量配置失败时抛出错误。
+     */
+    setRemoteAudioVolume(volume: number): Promise<void>;
+    /**
+     * 创建本地相机流并开始预览。
+     *
+     * 将返回的轨道绑定到预览视图；收到有效帧且视图已绑定后进入 `ready`。
+     *
+     * @returns 包含本地相机视频轨道的媒体流。
+     * @throws 模型不支持相机输入、配置无效、权限或采集启动失败时抛出错误。
+     */
+    createLocalCameraStream(options: {
+        videoFormat: RealtimeVideoFormat;
+        position: CameraPosition;
+        useMicrophone: boolean;
+    }): Promise<RealtimeMediaStream>;
+    /** 停止本地相机流并释放本地预览与 RTC 资源。 */
+    stopLocalCameraStream(): Promise<void>;
+    /**
+     * 切换前后置摄像头。
+     *
+     * 生成过程中调用时，SDK 会停止当前生成、切换摄像头，并使用缓存的生成
+     * 条件恢复生成；RTC 连接保持不变。连接或生成正在启动时不可切换。
+     *
+     * @returns 复用原视频轨道并更新摄像头位置后的本地媒体流。
+     */
+    switchCamera(): Promise<RealtimeMediaStream>;
+    /**
+     * 使用当前 Manager 创建的本地流建立实时连接。
+     *
+     * 创建实时会话、加入 RTC 房间并发布本地流，成功后启动会话心跳。
+     * 发布前并行检查相机亮度稳定性；5 秒内未通过检查时抛出
+     * `cameraExposureTimeout`，不发布媒体，接入方可改善光照后重试。
+     * 返回的远端媒体流在生成开始后承载远端生成画面。
+     *
+     * @param localStream 由 `createLocalCameraStream` 创建的本地媒体流。
+     * @returns 远端生成结果占位的媒体流。
+     * @throws 本地流不属于当前 Manager、已有活动连接、会话创建或进房
+     * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
+     */
+    connect(localStream: RealtimeMediaStream): Promise<RealtimeMediaStream>;
+    /** 断开实时连接并保留当前本地媒体预览。 */
+    disconnect(): Promise<void>;
+    /**
+     * 关闭当前实时生命周期并释放连接、本地媒体和 RTC Engine。
+     * 关闭期间重复调用会等待同一个释放任务；关闭完成后仍可重新创建本地流。
+     */
+    close(): Promise<void>;
+    /**
+     * 按需建立连接并开始生成。
+     *
+     * 尚未连接时先建立实时连接；已在生成时仅更新生成条件，不重启生成。
+     * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
+     *
+     * @param options.localStream 由 `createLocalCameraStream` 创建的本地媒体流。
+     * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
+     * @returns 承载远端生成画面的媒体流。
+     * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
+     * 或生成确认失败时抛出错误；失败时自动停止生成任务并释放连接资源。
+     */
+    startGeneration(options: {
+        localStream: RealtimeMediaStream;
+        context?: RealtimeContext;
+    }): Promise<RealtimeMediaStream>;
+}
+
+/**
+ * Xmax 服务环境。
+ */
+declare enum XmaxEnvironment {
+    /** 国内环境。 */
+    china = "china",
+    /** 海外环境。 */
+    global = "global"
+}
+/** 环境对应的 Xmax API Base URL。 */
+declare function apiBaseURL(environment: XmaxEnvironment): string;
+
+/**
+ * 控制 XmaxSDK 输出的日志类型（位掩码，可组合）。
+ */
+declare enum XmaxLoggerOption {
+    none = 0,
+    /** Room、API、Realtime、Storage 等业务运行日志。 */
+    business = 1,
+    /** RTC 网络质量和音视频运行统计，输出到 console.info。 */
+    performance = 2,
+    /** 输出全部 XmaxSDK 日志。 */
+    all = 3
+}
+/**
+ * 统一输出带 Xmax 前缀和类别的控制台日志。
+ *
+ * 调用方不得传入 API Key、Token、Secret、Authorization 或完整敏感响应。
+ */
+declare class XmaxLogger {
+    static readonly realtime: XmaxLogger;
+    static readonly rtc: XmaxLogger;
+    static readonly media: XmaxLogger;
+    static readonly api: XmaxLogger;
+    static readonly storage: XmaxLogger;
+    static readonly room: XmaxLogger;
+    static readonly stream: XmaxLogger;
+    static readonly render: XmaxLogger;
+    static readonly interaction: XmaxLogger;
+    static readonly permission: XmaxLogger;
+    private readonly category;
+    private constructor();
+    /**
+     * 更新 SDK 全局日志选项和细项语言，后一次配置覆盖前一次。
+     *
+     * @param options 输出的日志类型位掩码。
+     * @param environment 服务环境，决定日志细项语言（国内中文，海外英文）。
+     */
+    static configure(options: XmaxLoggerOption, environment?: XmaxEnvironment): void;
+    /** 选择日志细项文案；日志标题保持原有中英双语。 */
+    static localized(chinese: string, english: string): string;
+    /** 判断指定日志类型是否已开启。 */
+    static isEnabled(option: XmaxLoggerOption): boolean;
+    /** 输出调试日志。 */
+    debug(message: () => string, option?: XmaxLoggerOption): void;
+    /** 输出信息日志。 */
+    info(message: () => string, option?: XmaxLoggerOption): void;
+    /** 输出警告日志。 */
+    warning(message: () => string, option?: XmaxLoggerOption): void;
+    /** 输出错误日志。 */
+    error(message: () => string, option?: XmaxLoggerOption): void;
+    /** 按日志类型开关输出到控制台；未开启时不求值日志内容。 */
+    private log;
+}
+
+interface XmaxConfigurationInit {
+    /** 调用 Xmax 服务使用的 API Key。 */
+    apiKey: string;
+    /** SDK 连接的服务环境；默认为国内环境。 */
+    environment?: XmaxEnvironment;
+    /** SDK 输出的日志类型；默认为不输出日志。 */
+    loggerOptions?: XmaxLoggerOption;
+}
+/**
+ * SDK 全局配置。
+ */
+declare class XmaxConfiguration {
+    /** 调用 Xmax 服务使用的 API Key。 */
+    readonly apiKey: string;
+    /** SDK 连接的服务环境，同时决定日志细项语言：国内为中文，海外为英文。 */
+    readonly environment: XmaxEnvironment;
+    /** SDK 输出的日志类型；默认为不输出日志。 */
+    readonly loggerOptions: XmaxLoggerOption;
+    /**
+     * 创建 SDK 全局配置。
+     *
+     * @param init.apiKey 调用 Xmax 服务使用的 API Key。
+     * @param init.environment SDK 连接的服务环境；默认为国内环境。
+     * @param init.loggerOptions SDK 输出的日志类型；默认为空。
+     */
+    constructor(init: XmaxConfigurationInit);
+    /**
+     * 校验全局配置。
+     * @throws API Key 为空时抛出 `XmaxError`。
+     */
+    validate(): void;
+}
+
+/**
+ * SDK 的统一入口，负责创建实时和媒体服务组件。
+ */
+declare class XmaxClient {
+    /** 客户端使用的全局配置。 */
+    readonly configuration: XmaxConfiguration;
+    private readonly apiService;
+    /**
+     * 创建 SDK 客户端。
+     *
+     * 本地相机预览不依赖 API Key 校验；连接与生成等涉及服务端的操作
+     * 在实际调用时校验 API Key。
+     */
+    constructor(configuration: XmaxConfiguration);
+    /**
+     * 创建实时媒体 Manager。
+     *
+     * @param options 实时生成模型等业务配置。
+     * @returns 可用于本地相机预览、实时连接与生成的实时 Manager。
+     */
+    createRealtimeManager(options: RealtimeConfiguration): XmaxRealtimeManaging;
+    /**
+     * 创建媒体处理与能力查询 Service。
+     *
+     * @param model 媒体输入规则使用的模型，默认为 `x2-fast-1080p`。
+     */
+    createMediaService(model?: RealtimeModel): MediaServicing;
+    /**
+     * 创建文件存储 Service。
+     *
+     * @returns 可上传图片到对象存储的存储 Service，返回地址可用作参考图路径。
+     */
+    createStorageService(): StorageServicing;
+}
+
+/**
+ * 提供模型输入尺寸和平台媒体能力相关的业务规则。
+ * 模型输入尺寸与远端插帧能力。
+ */
+declare class MediaService implements MediaServicing {
+    readonly model: RealtimeModel;
+    /**
+     * 创建媒体服务。
+     *
+     * @param model 媒体输入规则使用的模型，默认为 `x2-fast-1080p`。
+     */
+    constructor(model?: RealtimeModel);
+    /** Web 插帧保留原始尺寸；/16 对齐由 GPU 内部补边处理，不缩小回传视频。 */
+    resolveFrameInterpolationSize(size: ModelSize): ModelSize;
+    /** WebGPU 适配器探测是异步的；实际性能和运行状态由渲染管线判断。 */
+    supportsFrameInterpolation(size: ModelSize): Promise<boolean>;
+    resolveModelInputSize(size: ModelSize): ModelSize;
+    /** 在对齐网格上选择满足面积限制且最接近目标的尺寸。 */
+    private boundedAlignedSize;
+    /** 校验尺寸为有限正数，并归一化为不小于 1 的整数。 */
+    private validatedSize;
+}
+
+/**
+ * Xmax API 支持的 HTTP 请求方法。
+ */
+declare enum ApiMethod {
+    get = "GET",
+    post = "POST",
+    put = "PUT",
+    delete = "DELETE"
+}
+/**
+ * 定义 Xmax API 的基础请求能力。
+ *
+ * 响应统一按 `{ success, code, message, data }` 信封解析，
+ * 各方法返回信封中的 `data` 字段。
+ */
+interface ApiServicing {
+    /**
+     * 发送请求并返回统一响应中的数据。
+     *
+     * @param method HTTP 请求方法。
+     * @param path 相对 Base URL 的请求路径。
+     * @param body JSON 请求体；无请求体时省略。
+     * @returns 统一响应中的 `data` 字段。
+     * @throws 配置无效、网络失败、业务失败或响应无法解析时抛出错误。
+     */
+    request<T>(method: ApiMethod, path: string, body?: unknown): Promise<T>;
+    /** 发送 GET 请求。 */
+    get<T>(path: string): Promise<T>;
+    /** 发送 POST 请求。 */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /** 发送 PUT 请求。 */
+    put<T>(path: string, body?: unknown): Promise<T>;
+    /** 发送 DELETE 请求。 */
+    delete<T>(path: string): Promise<T>;
+}
+
+/** 解析后的临时存储配置。 */
+interface TemporaryStorageConfiguration {
+    bucket: string;
+    region: string;
+    endpoint?: string;
+    prefix: string;
+    credentials: {
+        accessKeyID: string;
+        secretAccessKey: string;
+        sessionToken: string;
+    };
+}
+/** 对象存储直传客户端需要的最小接口。 */
+interface StorageObjectClient {
+    putObject(params: {
+        Bucket: string;
+        Region: string;
+        Key: string;
+        Body: Blob;
+        ContentType: string;
+        onProgress?: (info: {
+            loaded: number;
+            total: number;
+        }) => void;
+    }, callback: (error: {
+        message?: string;
+    } | null, data?: {
+        Location?: string;
+        ETag?: string;
+    }) => void): void;
+}
+/** 对象存储客户端工厂；生产实现按临时凭证创建 COS 客户端。 */
+type StorageObjectClientFactory = (configuration: TemporaryStorageConfiguration) => Promise<StorageObjectClient>;
+interface StorageServiceOptions {
+    /** Xmax API 请求组件。 */
+    apiService: ApiServicing;
+    /** 对象存储客户端工厂（可替换，测试用）。 */
+    clientFactory?: StorageObjectClientFactory;
+    /** 时间来源（可替换，测试用）。 */
+    dateGenerator?: () => Date;
+    /** 标识来源（可替换，测试用）。 */
+    identifierGenerator?: () => string;
+}
+/**
+ * 管理文件上传到对象存储。
+ *
+ * 上传直传不经过 Xmax 服务中转：先通过 `GET /cos/sts` 获取临时凭证，
+ * 再用临时凭证创建 COS 客户端直传；访问地址按 `Location`、自定义
+ * endpoint 或默认 COS 域名依次解析。
+ */
+declare class StorageService implements StorageServicing {
+    private readonly apiService;
+    private readonly clientFactory;
+    private readonly dateGenerator;
+    private readonly identifierGenerator;
+    /**
+     * 创建存储 Service。
+     *
+     * @param options.apiService Xmax API 请求组件。
+     * @param options.clientFactory 对象存储客户端工厂（可替换，测试用）。
+     * @param options.dateGenerator 时间来源（可替换，测试用）。
+     * @param options.identifierGenerator 标识来源（可替换，测试用）。
+     */
+    constructor(options: StorageServiceOptions);
+    /** 上传图片并返回访问地址。 */
+    uploadImage(options: StorageUploadOptions): Promise<StoredFile>;
+    /** 获取临时存储配置；字段不完整时抛出 API 错误。 */
+    private fetchStorageConfiguration;
+    /** 生成对象键：`${prefix}${毫秒时间戳}_${标识}_${文件名}`。 */
+    private makeObjectKey;
+    /** 生产环境 COS 客户端工厂：动态加载 cos-js-sdk-v5 并按临时凭证创建客户端。 */
+    private static cosClientFactory;
+    /** 调用对象存储上传并包装为 Promise。 */
+    private static putObject;
+    /**
+     * 解析对象访问地址：优先使用上传返回的 `Location`（补全协议），
+     * 其次拼接自定义 endpoint，最后回退到默认 COS 域名。
+     */
+    private static resolveObjectURL;
+    /** 统一构造上传体。 */
+    private static makeBody;
+    /** 校验文件名非空且不包含路径分隔符。 */
+    private static validateFileName;
+    /** 按文件名后缀推断内容类型。 */
+    private static inferContentType;
+    /** 格式化字节数用于日志输出。 */
+    private static formatByteCount;
+    /** 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。 */
+    private static nonEmpty;
+}
+
+interface RemoteFrameInterpolationOptions {
+    size: ModelSize;
+    targetFrameRate: number;
+    onActiveChange?: (active: boolean) => void;
+    onFailure: (error: unknown) => void;
+}
+
+/**
+ * 单轨视频视图（框架无关）。
+ *
+ * 通过 `attach(to:)` 挂载到任意容器元素；设置 `track` 后自动渲染。
+ * 轨道注册了渲染绑定时走绑定管线，否则按 `mediaStreamTrack` 直接渲染。
+ */
+declare class XmaxVideoView {
+    /** 视图根元素（div，内含一个 video 元素）。 */
+    readonly element: HTMLDivElement;
+    /** @internal 渲染视频帧的元素，供绑定管线使用。 */
+    readonly videoElement: HTMLVideoElement;
+    /** 首帧实际提交显示时调用（一次性；换轨后重新武装）。 */
+    frameDisplayHandler?: () => void;
+    private currentTrack?;
+    private contentMode;
+    private mirrored;
+    private hasNotifiedFrameDisplay;
+    private onPlaying?;
+    private videoFrameCallbackID?;
+    private frameNotificationSequence;
+    private interpolationOptions?;
+    private interpolationPipeline?;
+    private interpolationCanvas?;
+    private detached;
+    /**
+     * 创建单轨视频视图。
+     *
+     * @param options.videoContentMode 视频内容显示模式，默认 fill。
+     */
+    constructor(options?: {
+        videoContentMode?: VideoContentMode;
+    });
+    /** 当前显示的视频轨道；切换时自动解绑旧轨道。 */
+    get track(): RealtimeVideoTrack | undefined;
+    set track(track: RealtimeVideoTrack | undefined);
+    /** 视频内容在容器中的显示模式。 */
+    get videoContentMode(): VideoContentMode;
+    set videoContentMode(mode: VideoContentMode);
+    /** 本地预览是否镜像显示（仅影响显示，不影响发布流）。 */
+    get isMirrored(): boolean;
+    set isMirrored(mirrored: boolean);
+    /** 挂载到容器元素。 */
+    attach(to: HTMLElement): void;
+    /** 从容器元素移除。 */
+    detach(): void;
+    /** 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal */
+    setMediaStream(stream: MediaStream | null): void;
+    /** 由远端绑定注入配置；本地预览不走此管线。 @internal */
+    setFrameInterpolation(options?: RemoteFrameInterpolationOptions): void;
+    private startInterpolation;
+    private stopInterpolation;
+    /** 接入轨道画面：优先走注册的渲染绑定，否则按媒体轨直接渲染。 */
+    private attachTrack;
+    /** 解绑当前轨道并清空渲染内容。 */
+    private detachCurrentTrack;
+    /** 首帧提交合成器时通知；旧浏览器回退到 playing 近似判断。 */
+    private armFrameDisplayNotification;
+    /** 换流、解绑或卸载时取消观察，防止迟到的首帧归入下一条流。 */
+    private cancelFrameDisplayNotification;
+    /** 应用显示模式与镜像样式。 */
+    private applyContentMode;
+}
+
+/**
+ * 在本地预览和远端生成画面之间自动切换的视频容器（框架无关）。
+ *
+ * 设置远端轨道后，容器等待首帧实际提交显示再渐入远端画面；
+ * 远端轨道置空时立即恢复本地预览。
+ */
+declare class XmaxRealtimeVideoView {
+    /** 视图根元素。 */
+    readonly element: HTMLDivElement;
+    private readonly localVideoView;
+    private readonly remoteVideoView;
+    private currentLocalTrack?;
+    private currentRemoteTrack?;
+    private contentMode;
+    /**
+     * 创建实时视频容器。
+     *
+     * @param options.localTrack 需要持续预览的本地视频轨道。
+     * @param options.remoteTrack 需要覆盖显示的远端生成视频轨道。
+     * @param options.videoContentMode 本地与远端视频的内容显示模式，默认 fill。
+     */
+    constructor(options?: {
+        localTrack?: RealtimeVideoTrack;
+        remoteTrack?: RealtimeVideoTrack;
+        videoContentMode?: VideoContentMode;
+    });
+    /** 当前显示的本地视频轨道。 */
+    get localTrack(): RealtimeVideoTrack | undefined;
+    set localTrack(track: RealtimeVideoTrack | undefined);
+    /**
+     * 当前显示的远端生成视频轨道。
+     * 设置新轨道后等待首帧提交显示再渐入；置空时立即恢复本地预览。
+     */
+    get remoteTrack(): RealtimeVideoTrack | undefined;
+    set remoteTrack(track: RealtimeVideoTrack | undefined);
+    /** 视频内容在容器中的显示模式。 */
+    get videoContentMode(): VideoContentMode;
+    set videoContentMode(mode: VideoContentMode);
+    /** 本地预览是否镜像显示（前置摄像头）。 */
+    get isLocalMirrored(): boolean;
+    set isLocalMirrored(mirrored: boolean);
+    /** 挂载到容器元素。 */
+    attach(to: HTMLElement): void;
+    /** 从容器元素移除。 */
+    detach(): void;
+    /** 更新远端轨道绑定：重置渐入状态，等待首帧提交后再显示远端画面。 */
+    private updateRemoteTrack;
+    /** 远端首帧已提交：渐入远端画面。 */
+    private showRemoteVideo;
+}
+
+export { CameraPosition, type FrameInterpolationConfiguration, MediaService, type MediaServicing, type NetworkQualityLevel, type NetworkStatistics, type NetworkStatisticsListener, RealtimeConfiguration, type RealtimeConfigurationInit, RealtimeConnectionState, RealtimeContext, type RealtimeContextInit, type RealtimeLaunchTiming, type RealtimeLaunchTimingListener, RealtimeMediaStream, RealtimeModel, RealtimeReason, RealtimeState, type RealtimeStateListener, RealtimeVideoFormat, RealtimeVideoTrack, type RemoteVideoStatistics, type RemoteVideoStatisticsListener, StorageService, type StorageServicing, type StorageUploadOptions, StoredFile, VideoContentMode, type VideoStatistics, type VideoStatisticsListener, XmaxClient, XmaxConfiguration, type XmaxConfigurationInit, XmaxEnvironment, XmaxError, XmaxErrorCode, type XmaxErrorListener, XmaxLogger, XmaxLoggerOption, type XmaxRealtimeManaging, XmaxRealtimeVideoView, XmaxVideoView, apiBaseURL, defaultCameraVideoFormat, defaultFrameRate };