@xmaxai/web-sdk 1.0.4 → 1.0.6

package/dist/index.d.cts

@@ -1,37 +1,59 @@
-import { R as RealtimeVideoFormat, a as RealtimeVideoTrack, C as CameraPosition, V as VideoContentMode } from './VideoContentMode-BM97_H8V.cjs';
-export { b as RealtimeVideoEncoderPreference, c as RealtimeVideoFormatInit } from './VideoContentMode-BM97_H8V.cjs';
+import { R as RealtimeVideoFormat, a as RealtimeVideoTrack, C as CameraPosition, V as VideoContentMode, b as VideoRenderStatistics } from './VideoRenderStatistics-C7zqzfuS.cjs';
+export { c as RealtimeVideoEncoderPreference, d as RealtimeVideoFormatInit } from './VideoRenderStatistics-C7zqzfuS.cjs';
 
 /**
- * SDK 当前支持的实时生成模型。
+ * 实时媒体使用的 RTC 提供方；一个 Manager 生命周期内保持不变。
  */
-declare enum RealtimeModel {
+declare enum RtcProvider {
     /**
-     * Xmax X2.0 实时生成模型。
+     * 腾讯实时音视频。
      */
-    x2_0 = "x2.0",
+    trtc = "trtc",
     /**
-     * Xmax X2.0 TRTC 实时生成模型。
+     * 声网实时音视频。
      */
-    x2_0_trtc = "x2.0-trtc",
+    agora = "agora",
     /**
-     * Xmax X2.0 Agora 实时生成模型。
+     * 火山引擎实时音视频。
      */
-    x2_0_agora = "x2.0-agora",
-    /** X2.1 预览模型；媒体规格与 x2.0-trtc 相同。 */
+    vertc = "vertc"
+}
+
+/**
+ * SDK 当前支持的实时生成模型。
+ */
+declare enum RealtimeModel {
+    x2_0 = "x2.0",
+    x2_0_trtc = "x2.0-trtc",
     x2_1_preview = "x2.1-preview"
 }
+/** 内置模型或服务端新增的模型标识；自定义名称原样传给服务端。 */
+type RealtimeModelName = RealtimeModel | (string & {});
+/**
+ * 模型输入画面的像素尺寸。
+ */
 interface ModelSize {
     width: number;
     height: number;
 }
+/**
+ * 获取模型的显示名称。
+ */
+declare function modelDisplayName(model: RealtimeModelName): string;
 /**
  * 未指定视频规格时，各媒体来源使用的默认帧率。
  */
-declare function defaultFrameRate(_model: RealtimeModel): number;
+declare function defaultFrameRate(_model: RealtimeModelName): number;
 /**
  * 摄像头采集使用的默认视频规格。
  */
-declare function defaultCameraVideoFormat(model: RealtimeModel): RealtimeVideoFormat;
+declare function defaultCameraVideoFormat(model: RealtimeModelName): RealtimeVideoFormat;
+/**
+ * 查询 SDK 允许配置的 RTC 提供方，第一项为默认值。
+ * 未知模型默认沿用 x2.1-preview 的 Agora，也允许显式选择其他已接入的 RTC；
+ * 是否被该模型的服务端支持，由服务端决定。
+ */
+declare function supportedRtcProviders(model: RealtimeModelName): readonly RtcProvider[];
 
 /**
  * 定义媒体输入规则与平台媒体能力查询能力。
@@ -90,11 +112,11 @@ declare class StoredFile {
 }
 
 /**
- * 上传图片的参数。
+ * 上传图片或视频的参数。
  */
 interface StorageUploadOptions {
     /**
-     * 图片数据。
+     * 文件数据；File 作为 Blob 的子类可直接传入。
      */
     data: Blob | ArrayBuffer | Uint8Array;
     /**
@@ -102,7 +124,7 @@ interface StorageUploadOptions {
      */
     fileName: string;
     /**
-     * 图片 MIME 类型；缺省按文件名后缀推断。
+     * 文件 MIME 类型；缺省按文件名后缀推断。
      */
     contentType?: string;
     /**
@@ -111,104 +133,72 @@ interface StorageUploadOptions {
     onProgress?: (transferred: number, total: number) => void;
 }
 /**
- * 定义文件存储能力：上传图片到对象存储并返回访问地址。
+ * 定义图片、视频上传和视频下载能力。
  */
 interface StorageServicing {
     /**
      * 上传图片。
      *
-     * 从 Xmax 服务获取临时凭证后直传对象存储，返回的地址可用作
-     * 实时生成的参考图路径。
+     * 从 Xmax 服务获取临时凭证后直传对象存储。
      *
      * @returns 已存储文件信息。
      * @throws 参数无效、凭证获取失败或上传失败时抛出错误。
      */
     uploadImage(options: StorageUploadOptions): Promise<StoredFile>;
-}
-
-/**
- * 实时媒体使用的 RTC 提供方；一个 Manager 生命周期内保持不变。
- */
-declare enum RtcProvider {
     /**
-     * 腾讯实时音视频。
+     * 上传视频。
+     *
+     * 从 Xmax 服务获取临时凭证后，通过 COS putObject 普通上传原始文件。
+     * 不进行转码、压缩或分片上传；单个文件受 COS 普通上传的 5GB 上限约束。
+     *
+     * @returns 已存储文件信息。
+     * @throws 参数无效、凭证获取失败或上传失败时抛出错误。
      */
-    trtc = "trtc",
+    uploadVideo(options: StorageUploadOptions): Promise<StoredFile>;
     /**
-     * 声网实时音视频。
+     * 下载完整视频文件并触发浏览器保存；跨域地址需要允许 CORS。
+     *
+     * @param options.url 可直接访问的 HTTP(S) 视频地址。
+     * @param options.fileName 保存时建议使用的文件名。
+     * @param options.signal 用于取消网络下载的信号。
+     * @returns 文件读取完成并已触发浏览器保存，不代表文件已写入磁盘。
+     * @throws 参数无效、非浏览器环境、下载失败或主动取消时抛出错误。
      */
-    agora = "agora",
-    /** 火山引擎实时音视频。 */
-    vertc = "vertc"
+    downloadVideo(options: {
+        url: string;
+        fileName: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
 }
 
-/**
- * 远端视频插帧的开关与显示帧率配置。
- */
-interface FrameInterpolationConfiguration {
-    /**
-     * 是否请求开启远端插帧，默认 false。不支持时自动播放原视频。
-     */
-    enabled?: boolean;
-    /**
-     * 显示帧率上限，默认 60；每对源帧最多插入一帧。取值 1–60。
-     */
-    targetFrameRate?: number;
-}
-interface RealtimeConfigurationInit {
-    /**
-     * RTC 提供方，默认 TRTC；不根据模型名称自动推断。
-     */
-    provider?: RtcProvider;
-    /**
-     * 实时生成业务使用的模型。
-     */
-    model: RealtimeModel;
-    /**
-     * 是否默认开启远端生成画面的插帧，默认 false。
-     * frameInterpolation.enabled 显式设置时优先。
-     */
-    isFrameInterpolationEnabled?: boolean;
-    /**
-     * 插帧详细配置；enabled 显式设置时优先于简化开关。
-     */
-    frameInterpolation?: FrameInterpolationConfiguration;
-}
 /**
  * 创建实时 Manager 所需的业务配置。
  */
 declare class RealtimeConfiguration {
-    /**
-     * RTC 配置
-     */
-    readonly provider: RtcProvider;
-    /**
-     * 模型配置
-     */
     /**
      * 实时生成业务使用的模型。
      */
-    readonly model: RealtimeModel;
+    readonly model: RealtimeModelName;
     /**
-     * 远端插帧配置
+     * 实时连接使用的 RTC 提供方。
      */
+    readonly provider: RtcProvider;
     /**
      * 是否默认请求开启远端生成画面的插帧。
      */
     readonly isFrameInterpolationEnabled: boolean;
-    /**
-     * 已补全默认值的只读插帧配置。
-     */
-    readonly frameInterpolation: Readonly<Required<FrameInterpolationConfiguration>>;
     /**
      * 创建实时业务配置。
      *
-     * @param init.model 实时生成业务使用的模型。
-     * @param init.provider RTC 提供方，默认 TRTC；创建后不可切换。
-     * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧。
-     * @param init.frameInterpolation 插帧开关和显示帧率上限的详细配置。
+     * @param init.model 实时生成业务使用的模型；未知名称原样透传，默认配置同 x2.1-preview。
+     * @param init.provider RTC 提供方，默认按模型定义选择；必须受模型支持，创建后不可切换。
+     * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧，默认 false。
      */
-    constructor(init: RealtimeConfigurationInit);
+    constructor(init: {
+        model: RealtimeModelName;
+        provider?: RtcProvider;
+        isFrameInterpolationEnabled?: boolean;
+    });
 }
 
 /**
@@ -238,7 +228,32 @@ interface NetworkStatistics {
  */
 type NetworkStatisticsListener = (statistics: NetworkStatistics | undefined) => void;
 
+/**
+ * 服务端读取网络视频时使用的采样方式。
+ */
+declare enum RealtimeVideoSampleMethod {
+    time = "time",
+    fps = "fps"
+}
+/**
+ * 服务端可直接访问的网络视频及采样配置。
+ */
+interface RealtimeReferenceVideo {
+    /**
+     * HTTP 或 HTTPS 视频地址。
+     */
+    readonly path: string;
+    /**
+     * 服务端采样方式。
+     */
+    readonly sampleMethod: RealtimeVideoSampleMethod;
+}
+
 interface RealtimeContextInit {
+    /**
+     * 服务端直接读取的网络视频。
+     */
+    referenceVideo?: RealtimeReferenceVideo;
     /**
      * 实时生成使用的文本条件。
      */
@@ -252,6 +267,10 @@ interface RealtimeContextInit {
  * 单次实时生成任务的文本和参考资源上下文。
  */
 declare class RealtimeContext {
+    /**
+     * 服务端直接读取的网络视频。
+     */
+    readonly referenceVideo?: RealtimeReferenceVideo;
     /**
      * 生成条件
      */
@@ -632,6 +651,12 @@ interface XmaxRealtimeManaging {
      * 切换客户端插帧，不改变回传分辨率或重启任务。不支持时抛错且保留配置。
      */
     setFrameInterpolationEnabled(enabled: boolean): Promise<void>;
+    /**
+     * 手动升/降一档下行输出尺寸，便于调试 change_target_size；仅支持正在生成的 Agora 会话。
+     * 仅改变分辨率，成功发送后同步目标档位与插帧尺寸；自动调档仍保持开启。
+     * 到达 L1/L5 边界时不重复发送；发送成功不代表服务端已生效。
+     */
+    adjustDownlinkQuality(direction: "upgrade" | "downgrade"): Promise<void>;
     /**
      * 当前本地媒体预览音量，取值范围为 `0...1`。
      */
@@ -697,17 +722,55 @@ interface XmaxRealtimeManaging {
          */
         enableFrameValidation?: boolean;
     }): Promise<RealtimeMediaStream>;
+    /**
+     * 创建服务端直接读取的 HTTP/HTTPS 网络视频源，不采集或发布本地音视频。
+     * 本地预览静音播放一次，独立于服务端进度；创建源不会开始生成。
+     * 地址必须可由服务端直接访问，不转发浏览器 Cookie 或自定义鉴权头。
+     * @param options.videoFormat 模型输入及生成画面规格，不是上行编码参数。
+     * @param options.sampleMethod 服务端采样方式，默认 time。
+     * @param options.onFinish 当前任务收到服务端完成消息且生成就绪后调用一次，不代表尾帧已播放完。
+     * @throws 地址、格式无效或已有活动媒体源时抛错；close 释放源，disconnect 保留预览。
+     */
+    createNetworkVideoStream(options: {
+        url: string;
+        videoFormat: RealtimeVideoFormat;
+        sampleMethod?: RealtimeVideoSampleMethod;
+        onFinish?: () => void;
+    }): Promise<RealtimeMediaStream>;
+    /**
+     * 从本地 File/Blob 创建文件视频源，支持 TRTC、Agora 和 VeRTC，不访问摄像头或麦克风。
+     * 通过 Canvas 等比缩放补黑边，文件音频独立上行，本地预览始终静音。
+     * 应从用户点击事件直接调用以解锁播放；创建后停在首帧，startGeneration 时开始播放。
+     * @param options.videoFormat 期望的视频规格；尺寸自动匹配最接近宽高比的模型档位，等距时优先横屏。
+     * @param options.loop 是否循环播放文件音视频，默认 true。
+     * @param options.includeAudio 是否发送文件音频，默认 true；无音轨文件输出静音，false 不创建音频轨。
+     * @throws 提供方不支持、文件/格式无效、浏览器无法解码或播放受限时抛错。
+     */
+    createLocalVideoStream(options: {
+        file: Blob;
+        videoFormat: RealtimeVideoFormat;
+        loop?: boolean;
+        includeAudio?: boolean;
+    }): Promise<RealtimeMediaStream>;
     /**
      * 更新当前本地流的上行视频格式，立即应用于 RTC 编码器，不重连或重启生成。
      * 传入完整格式；未指定的码率和编码偏好按 RealtimeVideoFormat 默认规则解析。
      * 成功后更新本地轨道的 videoFormat，后续重连继续使用该格式。
      * 模型生成及远端插帧仍使用创建本地流时的格式；此接口不改变生成尺寸。
      * 实际发送规格受设备、浏览器和网络影响，应通过统计回调确认。
+     * Agora 上行自适应以本次成功应用的完整格式作为新的 L1 基准，后续五档按比例调整尺寸和帧率。
      *
      * @param videoFormat 本次完整的上行尺寸、帧率和编码配置。
-     * @throws 无本地相机流、其他操作进行中、参数无效或 RTC 更新失败时抛错。
+     * @throws 无本地相机或文件视频流、其他操作进行中、参数无效或 RTC 更新失败时抛错。
+     */
+    updateUplinkVideoFormat(videoFormat: RealtimeVideoFormat): Promise<void>;
+    /**
+     * 试验性上行调帧接口：连接建立后使用，保留最近应用的宽高、码率区间和编码偏好。
+     * 成功后更新本地轨道格式，重连沿用；不修改服务端生成或输出规格。
+     * 手动调用会重置上行质量样本，并以成功后的完整格式作为新的自适应 L1 基准。
+     * 仍会重新提交完整编码配置，不保证 RTC 内部自适应状态不受影响，需用实际统计验证。
      */
-    updateVideoFormat(videoFormat: RealtimeVideoFormat): Promise<void>;
+    updateUplinkFrameRate(fps: number): Promise<void>;
     /**
      * 停止本地相机流并释放本地预览与 RTC 资源。
      */
@@ -724,11 +787,11 @@ interface XmaxRealtimeManaging {
     /**
      * 使用当前 Manager 创建的本地流建立实时连接。
      *
-     * 创建实时会话、加入 RTC 房间并发布本地流，成功后启动会话心跳。
+     * 创建实时会话、加入 RTC 房间并启动会话心跳；摄像头源发布本地流，网络视频源仅接收。
      * 启用帧检测时，发布前并行等待相机预热（固定 200ms），避免把黑帧推给 RTC。
      * 返回的远端媒体流在生成开始后承载远端生成画面。
      *
-     * @param localStream 由 `createLocalCameraStream` 创建的本地媒体流。
+     * @param localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
      * @returns 远端生成结果占位的媒体流。
      * @throws 本地流不属于当前 Manager、已有活动连接、会话创建或进房
      * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
@@ -749,7 +812,7 @@ interface XmaxRealtimeManaging {
      * 尚未连接时先建立实时连接；已在生成时仅更新生成条件，不重启生成。
      * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
      *
-     * @param options.localStream 由 `createLocalCameraStream` 创建的本地媒体流。
+     * @param options.localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
      * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
      * @returns 承载远端生成画面的媒体流。
      * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
@@ -913,7 +976,174 @@ declare class XmaxConfiguration {
 }
 
 /**
- * SDK 的统一入口，负责创建实时和媒体服务组件。
+ * 非实时视频的输出质量。
+ */
+declare enum NonRealtimeQuality {
+    sd = "sd",
+    hd = "hd"
+}
+/**
+ * 服务端任务状态；上传进度不属于任务状态。
+ */
+declare enum NonRealtimeTaskStatus {
+    submitted = "submitted",
+    processing = "processing",
+    completed = "completed",
+    error = "error"
+}
+/**
+ * 提交非实时任务的参数；资源必须来自 Xmax 上传流程，不能使用 blob URL 或本地路径。
+ */
+interface NonRealtimeTaskOptions {
+    /**
+     * 模型标识。
+     */
+    model: string;
+    /**
+     * 已上传源视频的 URL。
+     */
+    videoPath: string;
+    /**
+     * 生成指令；去除首尾空白后为 1–1024 个字符。
+     */
+    prompt: string;
+    /**
+     * 已上传参考图片的 URL；省略表示不使用参考图。
+     */
+    referencePath?: string;
+    /**
+     * 输出质量。
+     */
+    quality: NonRealtimeQuality;
+    /**
+     * 可选的处理帧率；仅接受协议支持的整数，省略时沿用源视频帧率（含小数）。
+     */
+    fps?: number;
+}
+/**
+ * 非实时生成结果；缺失或 null 的服务端字段规范化为 undefined。
+ */
+interface NonRealtimeResult {
+    readonly url?: string;
+    readonly uploadError?: string;
+    readonly uploadStatus?: string;
+    readonly finalizeDurationMs?: number;
+    readonly compressionLevel?: string;
+    readonly frameCount?: number;
+    readonly fps?: number;
+    readonly durationMs?: number;
+    readonly fileSizeBytes?: number;
+    readonly droppedFrameCount?: number;
+    readonly originalFileSizeBytes?: number;
+}
+/**
+ * 非实时任务快照；uid 和 status 为 SDK 查询、恢复及轮询所需字段。
+ * 时间戳保持服务端原始字符串，不推断时区。
+ */
+interface NonRealtimeTask {
+    readonly uid: string;
+    readonly status: NonRealtimeTaskStatus;
+    readonly userUid?: string;
+    readonly prompt?: string;
+    readonly videoPath?: string;
+    readonly referencePath?: string;
+    readonly processorId?: string;
+    readonly quality?: NonRealtimeQuality;
+    readonly requestedFps?: number;
+    readonly resolvedFps?: number;
+    readonly retryCount?: number;
+    readonly videoDurationSeconds?: number;
+    readonly billableDurationSeconds?: number;
+    readonly chargePoints?: number;
+    readonly result?: NonRealtimeResult;
+    readonly processStartTime?: string;
+    readonly createTimestamp?: string;
+    readonly updateTimestamp?: string;
+}
+/**
+ * 分页查询选项。
+ */
+interface NonRealtimeTaskListOptions {
+    /**
+     * 从 1 开始的页码，默认 1。
+     */
+    pageNumber?: number;
+    /**
+     * 每页数量，1–100，默认 10。
+     */
+    pageSize?: number;
+    /**
+     * 可选的任务状态筛选。
+     */
+    status?: NonRealtimeTaskStatus;
+}
+/**
+ * 按创建时间从新到旧排列的任务页。
+ */
+interface NonRealtimeTaskPage {
+    readonly pageNumber: number;
+    readonly pageSize: number;
+    readonly total: number;
+    readonly list: readonly NonRealtimeTask[];
+}
+
+/**
+ * 本地任务等待选项；所有时间单位均为毫秒。
+ */
+interface NonRealtimeWaitOptions {
+    /**
+     * 成功查询后等待多久再查询，默认 2000；必须为正数。
+     */
+    intervalMs?: number;
+    /**
+     * 总等待时限，必须为正数；省略时持续等待直至终态或取消。
+     */
+    timeoutMs?: number;
+    /**
+     * 连续瞬时查询错误允许重试的次数，默认 3；成功查询后重置，0 表示不重试。
+     */
+    maxConsecutiveRetries?: number;
+    /**
+     * 停止轮询及正在进行的查询，不取消服务端任务或退款。
+     */
+    signal?: AbortSignal;
+    /**
+     * 每次成功查询的任务快照（含终态），不是生成百分比；回调异常不影响轮询。
+     */
+    onTaskUpdated?: (task: NonRealtimeTask) => void;
+}
+/**
+ * 非实时视频任务能力；各任务和等待操作相互独立，不维护唯一的当前任务。
+ */
+interface XmaxNonRealtimeManaging {
+    /**
+     * 提交并立即返回任务；不等待生成，不自动上传资源，也不自动重试提交请求。
+     * 超时或响应解析失败不能证明服务端未创建任务，重复提交可能再次扣费。
+     */
+    submitTask(options: NonRealtimeTaskOptions): Promise<NonRealtimeTask>;
+    /**
+     * 查询单个任务；服务端 error 状态原样返回，不作为 HTTP 查询失败抛出。
+     */
+    getTask(taskUid: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<NonRealtimeTask>;
+    /**
+     * 批量查询最多 100 个 ID，去重后按请求顺序返回；任一任务无权限或不存在则整体失败。
+     */
+    getTasks(taskUids: readonly string[]): Promise<readonly NonRealtimeTask[]>;
+    /**
+     * 查询任务列表；默认第一页、每页 10 条，最多 100 条。
+     */
+    listTasks(options?: NonRealtimeTaskListOptions): Promise<NonRealtimeTaskPage>;
+    /**
+     * 串行轮询直到 completed 且结果 URL 可用；任务 error 时抛出 NonRealtimeTaskError。
+     * 超时、取消只停止本地等待，之后可使用同一任务 ID 继续查询或等待。
+     */
+    waitForCompletion(taskUid: string, options?: NonRealtimeWaitOptions): Promise<NonRealtimeTask>;
+}
+
+/**
+ * SDK 的统一入口，负责创建实时、非实时和媒体服务组件。
  */
 declare class XmaxClient {
     /**
@@ -942,20 +1172,39 @@ declare class XmaxClient {
      * @returns 可用于本地相机预览、实时连接与生成的实时 Manager。
      */
     createRealtimeManager(options: RealtimeConfiguration): XmaxRealtimeManaging;
+    /**
+     * 创建非实时视频任务 Manager，使用全局 API Key 和当前环境的非实时任务服务地址。
+     * 本方法不发起网络请求或加载 RTC，任务由服务端持久化，可按 ID 恢复查询。
+     */
+    createNonRealtimeManager(): XmaxNonRealtimeManaging;
     /**
      * 创建媒体处理与能力查询 Service。
      *
      * @param model 媒体输入规则使用的模型，默认为 `x2.0-trtc`。
      */
-    createMediaService(model?: RealtimeModel): MediaServicing;
+    createMediaService(model?: RealtimeModelName): MediaServicing;
     /**
      * 创建文件存储 Service。
      *
-     * @returns 可上传图片到对象存储的存储 Service，返回地址可用作参考图路径。
+     * @returns 可上传图片和视频到对象存储的存储 Service。
      */
     createStorageService(): StorageServicing;
 }
 
+/**
+ * 服务端任务失败或终态结果不可用；保留最后的任务快照供接入方展示及恢复查询。
+ */
+declare class NonRealtimeTaskError extends XmaxError {
+    /**
+     * 失败上下文
+     */
+    readonly task: NonRealtimeTask;
+    /**
+     * 使用 API 错误分类，不虚构服务端未返回的业务错误码。
+     */
+    constructor(task: NonRealtimeTask, message: string);
+}
+
 /**
  * 提供模型输入尺寸和平台媒体能力相关的业务规则。
  * 模型输入尺寸与远端插帧能力。
@@ -964,13 +1213,13 @@ declare class MediaService implements MediaServicing {
     /**
      * 模型约束
      */
-    readonly model: RealtimeModel;
+    readonly model: RealtimeModelName;
     /**
      * 创建媒体服务。
      *
      * @param model 媒体输入规则使用的模型，默认为 `x2.0-trtc`。
      */
-    constructor(model?: RealtimeModel);
+    constructor(model?: RealtimeModelName);
     /**
      * Web 插帧保留原始尺寸；/16 对齐由 GPU 内部补边处理，不缩小回传视频。
      */
@@ -1002,6 +1251,13 @@ declare enum ApiMethod {
     put = "PUT",
     delete = "DELETE"
 }
+/**
+ * 请求控制选项；signal 仅取消本地 HTTP 请求，不撤销服务端已执行的操作。
+ */
+interface ApiRequestOptions {
+    signal?: AbortSignal;
+    keepalive?: boolean;
+}
 /**
  * 定义 Xmax API 的基础请求能力。
  *
@@ -1018,11 +1274,11 @@ interface ApiServicing {
      * @returns 统一响应中的 `data` 字段。
      * @throws 配置无效、网络失败、业务失败或响应无法解析时抛出错误。
      */
-    request<T>(method: ApiMethod, path: string, body?: unknown): Promise<T>;
+    request<T>(method: ApiMethod, path: string, body?: unknown, options?: ApiRequestOptions): Promise<T>;
     /**
      * 发送 GET 请求。
      */
-    get<T>(path: string): Promise<T>;
+    get<T>(path: string, options?: ApiRequestOptions): Promise<T>;
     /**
      * 发送 POST 请求。
      */
@@ -1103,7 +1359,7 @@ interface StorageServiceOptions {
     identifierGenerator?: () => string;
 }
 /**
- * 管理文件上传到对象存储。
+ * 管理文件上传和视频下载。
  *
  * 上传直传不经过 Xmax 服务中转：先通过 `GET /cos/sts` 获取临时凭证，
  * 再用临时凭证创建 COS 客户端直传；访问地址按 `Location`、自定义
@@ -1136,6 +1392,18 @@ declare class StorageService implements StorageServicing {
      * 上传图片并返回访问地址。
      */
     uploadImage(options: StorageUploadOptions): Promise<StoredFile>;
+    /**
+     * 普通上传原始视频并返回访问地址，不进行转码、压缩或分片。
+     */
+    uploadVideo(options: StorageUploadOptions): Promise<StoredFile>;
+    /**
+     * 下载原始视频文件并交给浏览器保存，支持取消网络下载。
+     */
+    downloadVideo(options: Parameters<StorageServicing["downloadVideo"]>[0]): Promise<void>;
+    /**
+     * 获取临时凭证并通过 COS putObject 上传文件，统一处理进度、结果和错误。
+     */
+    private upload;
     /**
      * 获取临时存储配置；字段不完整时抛出 API 错误。
      */
@@ -1181,8 +1449,11 @@ declare class StorageService implements StorageServicing {
 
 interface RemoteFrameInterpolationOptions {
     size: ModelSize;
-    targetFrameRate: number;
     onActiveChange?: (active: boolean) => void;
+    /**
+     * 实际提交画布呈现时通知，参数表示是否为插值帧。
+     */
+    onFramePresented?: (interpolated: boolean) => void;
     onFailure: (error: unknown) => void;
 }
 
@@ -1230,6 +1501,10 @@ declare class XmaxVideoView {
     private interpolationOptions?;
     private interpolationPipeline?;
     private interpolationCanvas?;
+    /**
+     * 呈现统计组件
+     */
+    private readonly statisticsController;
     /**
      * DOM 挂载状态
      */
@@ -1246,6 +1521,14 @@ declare class XmaxVideoView {
      * 当前显示的视频轨道；切换时自动解绑旧轨道。
      */
     get track(): RealtimeVideoTrack | undefined;
+    /**
+     * 每秒接收当前视图的呈现统计；换流、卸载或不可统计时返回 undefined。
+     */
+    get renderStatisticsHandler(): ((statistics?: VideoRenderStatistics) => void) | undefined;
+    /**
+     * 更新统计回调，不影响播放；移除回调时停止采集。
+     */
+    set renderStatisticsHandler(handler: ((statistics?: VideoRenderStatistics) => void) | undefined);
     /**
      * 解绑旧轨道后接入新轨道，并为新内容重新启用一次性首帧通知。
      */
@@ -1274,6 +1557,10 @@ declare class XmaxVideoView {
      * 从容器元素移除。
      */
     detach(): void;
+    /**
+     * 设置网络视频预览；静音播放一次，不捕获或发布媒体轨道。 @internal
+     */
+    setVideoURL(url: string | null): void;
     /**
      * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
      */
@@ -1310,6 +1597,10 @@ declare class XmaxVideoView {
      * 应用显示模式与镜像样式。
      */
     private applyContentMode;
+    /**
+     * 视图未卸载时启动呈现统计，采样及媒体就绪检查由统计组件负责。
+     */
+    private startRenderStatistics;
 }
 
 /**
@@ -1400,4 +1691,4 @@ declare class XmaxRealtimeVideoView {
     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, RtcProvider, 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 };
+export { CameraPosition, MediaService, type MediaServicing, type NetworkQualityLevel, type NetworkStatistics, type NetworkStatisticsListener, NonRealtimeQuality, type NonRealtimeResult, type NonRealtimeTask, NonRealtimeTaskError, type NonRealtimeTaskListOptions, type NonRealtimeTaskOptions, type NonRealtimeTaskPage, NonRealtimeTaskStatus, type NonRealtimeWaitOptions, RealtimeConfiguration, RealtimeConnectionState, RealtimeContext, type RealtimeContextInit, type RealtimeLaunchTiming, type RealtimeLaunchTimingListener, RealtimeMediaStream, RealtimeModel, type RealtimeModelName, RealtimeReason, type RealtimeReferenceVideo, RealtimeState, type RealtimeStateListener, RealtimeVideoFormat, RealtimeVideoSampleMethod, RealtimeVideoTrack, type RemoteVideoStatistics, type RemoteVideoStatisticsListener, RtcProvider, StorageService, type StorageServicing, type StorageUploadOptions, StoredFile, VideoContentMode, VideoRenderStatistics, type VideoStatistics, type VideoStatisticsListener, XmaxClient, XmaxConfiguration, type XmaxConfigurationInit, XmaxEnvironment, XmaxError, XmaxErrorCode, type XmaxErrorListener, XmaxLogger, XmaxLoggerOption, type XmaxNonRealtimeManaging, type XmaxRealtimeManaging, XmaxRealtimeVideoView, XmaxVideoView, apiBaseURL, defaultCameraVideoFormat, defaultFrameRate, modelDisplayName, supportedRtcProviders };