seacloud-sdk 0.11.6 → 0.11.8

package/dist/index.d.ts

@@ -9923,6 +9923,8 @@ declare function viduQ2(params: ViduQ2Params): Promise<ViduQ2Resource[]>;
 interface ViduQ2ReferenceSubject {
     /**
      * 主体id，在提示词中可以通过 @主体id 的方式使用
+     * 可以使用任意字符串，建议使用有意义的名称（如 'person', 'dog', 'car' 等）
+     * 例如：id: 'girl' 可以在 prompt 中使用 '@girl 在跳舞'
      */
     id: string;
     /**
@@ -9933,21 +9935,34 @@ interface ViduQ2ReferenceSubject {
 interface ViduQ2I2vReferenceParams {
     /**
      * 文本提示词，必填
-     * 可以通过@主体id 来表示主体内容
-     * 例如："@1 和 @2 在一起吃火锅，并且旁白音说火锅大家都爱吃。"
+     * 使用 subjects 时，可以通过 @主体id 来引用主体内容
+     * 例如："@1 和 @2 在公园里一起玩耍"
      * 注：字符长度不能超过 2000 个字符
      */
     prompt: string;
     /**
-     * 参考图像列表（URL或Base64），与subjects参数互斥
-     * 支持1-7张参考图片
+     * 主体列表（推荐使用），与 images 参数互斥
+     * 每个主体包含：
+     * - id: 主体ID，在 prompt 中通过 @id 引用
+     * - images: 该主体的图片URL列表（每个主体最多3张图片）
+     *
+     * 推荐使用 subjects 而非 images，支持多主体精确控制
+     *
+     * @example
+     * subjects: [
+     *   { id: '1', images: ['https://example.com/person1.jpg'] },
+     *   { id: '2', images: ['https://example.com/dog.jpg'] }
+     * ]
+     * prompt: '@1 和 @2 在公园里一起玩耍'
      */
-    images?: string[];
+    subjects?: ViduQ2ReferenceSubject[];
     /**
-     * 主体列表，与images参数互斥
-     * 每个主体可以有多张图片（最多3张），并在prompt中通过@主体id引用
+     * 参考图像列表（已废弃，推荐使用 subjects），与 subjects 参数互斥
+     * 支持1-7张参考图片
+     *
+     * @deprecated 建议使用 subjects 参数以获得更好的主体控制
      */
-    subjects?: ViduQ2ReferenceSubject[];
+    images?: string[];
     /**
      * 音色ID，使用预设音色或复刻音色
      * 为空时系统会自动推荐音色并使用
@@ -10022,18 +10037,24 @@ interface ViduQ2I2vReferenceResource {
     [key: string]: any;
 }
 /**
- * viduq2_i2v_reference
+ * viduQ2I2vReference
  *
- * Vidu Q2 Reference-to-Video generation implementation.
+ * Vidu Q2 参考图生视频（升级版 - 推荐使用 subjects）
  *
- * Model: viduq2 (最新模型)
- * Features: 最新模型，支持参考图生视频，高质量输出，支持主体一致性
- * Duration: 1-8秒 (可选)
- * Resolution: 根据时长动态调整
- * Images: 1-7张参考图片，或使用subjects定义多个主体
+ * Model: viduq2_i2v_reference (最新升级模型)
+ * Features:
+ * - 支持多主体精确控制（通过 subjects 参数）
+ * - 高质量视频输出，支持主体一致性
+ * - 支持音视频直出能力（audio=true）
+ * - 每个主体最多支持3张参考图片
+ * Duration: 1-8秒
+ * Resolution: 540p | 720p | 1080p
+ *
+ * 重要升级：
+ * - ✅ 推荐使用 subjects 参数（支持多主体和 @id 引用）
+ * - ⚠️  images 参数已废弃，建议迁移到 subjects
  *
  * API Documentation: https://platform.vidu.cn/docs/reference-to-video
- * Status API: https://platform.vidu.cn/docs/get-generation
  *
  * @example
  * ```typescript
@@ -10041,27 +10062,42 @@ interface ViduQ2I2vReferenceResource {
  *
  * initSeacloud('your-api-key');
  *
- * // 方式1: 使用普通参考图片列表
- * const result1 = await viduQ2I2vReference({
- *   prompt: '一只可爱的小猫在花园里玩耍',
- *   images: ['https://example.com/cat.jpg'],
- *   duration: 5,
+ * // 推荐方式：使用 subjects（支持多主体精确控制）
+ * // id 可以使用任意字符串，建议使用有意义的名称
+ * const result = await viduQ2I2vReference({
+ *   prompt: '@person 和 @dog 在公园里一起玩耍',
+ *   subjects: [
+ *     {
+ *       id: 'person',  // 使用有意义的 id
+ *       images: ['https://example.com/person.jpg']
+ *     },
+ *     {
+ *       id: 'dog',  // 使用有意义的 id
+ *       images: ['https://example.com/dog.jpg']
+ *     }
+ *   ],
+ *   duration: 4,
  *   resolution: '720p',
+ *   audio: true,  // 启用音视频直出
  * });
  *
- * // 方式2: 使用主体列表（支持多主体和主体引用）
+ * // 多图参考（每个主体最多3张图片）
  * const result2 = await viduQ2I2vReference({
- *   prompt: '@1 和 @2 在一起吃火锅，并且旁白音说火锅大家都爱吃。',
+ *   prompt: '@girl 在跳舞',
  *   subjects: [
- *     { id: '1', images: ['https://example.com/person1.jpg'] },
- *     { id: '2', images: ['https://example.com/person2.jpg'] }
+ *     {
+ *       id: 'girl',  // id 可以是任意字符串
+ *       images: [
+ *         'https://example.com/person1.jpg',
+ *         'https://example.com/person2.jpg',
+ *         'https://example.com/person3.jpg'
+ *       ]
+ *     }
  *   ],
- *   audio: true,
- *   voice_id: 'voice_123',
  *   duration: 8,
  * });
  *
- * console.log(result); // 返回生成的资源列表
+ * console.log(result[0].url); // 返回生成的视频URL
  * ```
  *
  * @param params 请求参数，详见 ViduQ2I2vReferenceParams 接口定义