简体中文 | English

MV Trustee Mode API 技能

调用 MV Trustee Mode API，执行完整的 MV 生成工作流。项目创建与任务提交在脚本中已合并为一步——仅需调用一次 execute_workflow；切勿分别调用 create 和 submit。

⚠️ 安装前请务必审阅

安装前请仔细审阅以下说明。 该技能将：

1. 网络请求 —— 调用 Giggle.pro API 执行 MV 生成

依赖要求：python3 (>=3.6)、系统环境变量 GIGGLE_API_KEY，以及 pip 包：requests

出错不重试：若脚本执行过程中发生错误，不得重试。请直接向用户报告错误并终止流程。

首次使用前的必要配置

执行任何操作前，请确认用户已完成 API Key 配置。

API Key：登录 Giggle.pro，在账户设置中获取 API Key。

配置方式：设置系统环境变量 GIGGLE_API_KEY

• export GIGGLE_API_KEY=your_api_key

验证步骤：

1. 确认用户已在系统环境中配置 GIGGLE_API_KEY
2. 若未配置，需引导用户完成配置：

   您好！在使用 MV 生成功能前，您需要先配置 API Key。请前往 Giggle.pro 获取您的 API Key，然后在终端中运行 export GIGGLE_API_KEY=your_api_key。

3. 等待用户完成配置后，再继续后续工作流

两种音乐生成模式

通用参数（所有模式均必需）

• reference_image 或 reference_image_url：参考图像——至少提供其一（asset_id 或可下载 URL）。也支持 Base64 编码图像，例如："iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="。使用 Base64 时，请直接传入原始 Base64 字符串，不要添加 data:image/xxx;base64 前缀。
• aspect：画面宽高比，取值为 16:9 或 9:16
• scene_description：视觉场景描述，默认为空——仅当用户明确提及“场景”、“视觉描述”或“视觉风格”时才填写（最多 200 字符）
• subtitle_enabled：是否启用字幕，默认为 false

模式专属参数

Prompt 模式：

• prompt：音乐描述（必需）
• vocal_gender：人声性别 —— 可选值：male / female / auto（默认 auto）
• instrumental：纯器乐（可选，默认 false）

Custom 模式：

• lyrics：歌词内容（必需）
• style：音乐风格（必需）
• title：歌曲标题（必需）

工作流函数

使用 execute_workflow 运行完整工作流——调用一次并等待返回结果。内部流程包括：创建项目 + 提交任务（已合并）→ 轮询进度（每 3 秒一次）→ 检测并支付待支付项 → 等待任务完成（最长 1 小时）。

重要提示：

• 切勿单独调用 create_project 和 submit_mv_task —— 请始终使用 execute_workflow 或 create_and_submit
• 调用后只需等待函数返回；所有中间步骤均由系统自动处理

函数签名

execute_workflow(
    music_generate_type: str,      # 模式：prompt / custom
    aspect: str,                    # 宽高比：16:9 或 9:16
    project_name: str,              # 项目名称
    reference_image: str = "",      # 参考图像 asset_id（与 reference_image_url 互斥）
    reference_image_url: str = "",  # 参考图像 URL 或 Base64（与 reference_image 互斥）
    scene_description: str = "",    # 场景描述，默认为空
    subtitle_enabled: bool = False, # 是否启用字幕，默认 False
    # Prompt 模式参数
    prompt: str = "",
    vocal_gender: str = "auto",
    instrumental: bool = False,
    # Custom 模式参数
    lyrics: str = "",
    style: str = "",
    title: str = "",
)

参数提取规则

1. reference_image 与 reference_image_url：二者至少提供其一。使用 reference_image 传入 asset_id；使用 reference_image_url 传入图像 URL 或 Base64 字符串。
2. scene_description：默认为空——仅当用户明确提及“场景”、“视觉描述”或“视觉风格”时才填写。
3. subtitle_enabled：默认为 False——仅当用户明确要求启用字幕时才设为 True。
4. aspect：若用户提及“竖屏”、“垂直”或“9:16”，则使用 9:16；否则默认 16:9。
5. 模式选择：“描述音乐 / 使用 prompt” → prompt 模式；“这是我的歌词 / 歌词是……” → custom 模式。

示例

Prompt 模式：

api = MVTrusteeAPI()
result = api.execute_workflow(
    music_generate_type="prompt",
    aspect="16:9",
    project_name="My MV",
    reference_image_url="https://example.com/ref.jpg",
    prompt="Upbeat pop, sunny beach vibe",
    vocal_gender="female"
)

Custom 模式（用户提供歌词）：

result = api.execute_workflow(
    music_generate_type="custom",
    aspect="9:16",
    project_name="Lyrics MV",
    reference_image="asset_xxx",
    lyrics="Verse 1: Spring breeze on my face...",
    style="pop",
    title="Spring Song"
)

含场景描述（当用户明确描述场景时）：

result = api.execute_workflow(
    music_generate_type="prompt",
    aspect="16:9",
    project_name="Scene MV",
    reference_image_url="https://...",
    prompt="Electronic dance music",
    scene_description="City nightscape, neon lights, flowing traffic"
)

提交任务 API 请求示例（Prompt 模式）

提交接口（/api/v1/trustee_mode/mv/submit）请求体：

{
  "project_id": "",
  "music_generate_type": "prompt",
  "prompt": "A cheerful pop song",
  "vocal_gender": "female",
  "instrumental": false,
  "reference_image_url": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBxMTEhUT...(base64 image data)",
  "scene_description": "A romantic beach walk at sunset, waves gently lapping the shore, pink sky gradient",
  "aspect": "16:9",
  "subtitle_enabled": false
}

注意：reference_image（asset_id）与 reference_image_url（URL 或 Base64）互斥，不可同时提供。

Custom 模式：

{
  "project_id": "",
  "music_generate_type": "custom",
  "lyrics": "Verse 1:nStanding by the sea watching the sunsetnMemories rush in like wavesnnChorus:nLet the sea breeze blow away all worriesnIn this golden momentnWe found each othern",
  "style": "pop ballad",
  "title": "Seaside Memories",
  "reference_image": "",
  "scene_description": "A couple walking on the beach at dusk, long shadows, orange-red sky gradient",
  "aspect": "9:16",
  "subtitle_enabled": false
}

查询进度 API 响应示例

查询接口（/api/v1/trustee_mode/mv/query）响应（全部步骤已完成）：

{
  "code": 200,
  "msg": "success",
  "uuid": "",
  "data": {
    "project_id": "",
    "video_asset": {
      "asset_id": "",
      "download_url": "https://assets.giggle.pro/private/...",
      "thumbnail_url": "https://assets.giggle.pro/private/...",
      "signed_url": "https://assets.giggle.pro/private/...",
      "duration": 0
    },
    "shot_count": 0,
    "current_step": "editor",
    "completed_steps": "music-generate,storyboard,shot,editor",
    "pay_status": "paid",
    "status": "completed",
    "err_msg": "",
    "steps": [...]
  }
}

注意：当 pay_status 为 pending 时，需调用支付接口。当所有 steps 均已完成时，video_asset.download_url 将有有效值——请返回完整的带签名 URL。正确格式如下：

https://assets.giggle.pro/private/ai_director/348e4956c7bd4f763b/qzjc7gwkpf.mp4?Policy=...&Key-Pair-Id=...&Signature=...&response-content-disposition=attachment

错误示例（仅提供未签名 URL）：

https://assets.giggle.pro/private/ai_director/348e4956c7bd4f763b/qzjc7gwkpf.mp4

支付 API 请求与响应

支付接口（/api/v1/trustee_mode/mv/pay）：

请求体：

{
  "project_id": ""
}

响应：

{
  "code": 200,
  "msg": "success",
  "uuid": "",
  "data": {
    "order_id": "",
    "price": 580
  }
}

重试 API 请求示例

当某一步骤失败时，请引导用户调用重试接口，从该步骤恢复执行：

{
  "project_id": "",
  "current_step": "shot"
}

注意：current_step 是需重试的步骤名（例如：music-generate、storyboard、shot、editor）。

create_and_submit（可选）

若您仅需创建项目并提交任务，而无需等待任务完成，可使用 create_and_submit。切勿 单独调用 create_project 和 submit_mv_task：

api = MVTrusteeAPI()
r = api.create_and_submit(
    project_name="My MV",
    music_generate_type="prompt",
    aspect="16:9",
    reference_image_url="https://...",
    prompt="Upbeat pop"
)
# 返回 project_id，供后续手动查询或支付

返回值

成功时返回：

{
    "code": 200,
    "msg": "success",
    "data": {
        "project_id": "...",
        "download_url": "https://...",
        "video_asset": {...},
        "status": "completed"
    }
}

失败时返回错误信息。

故障排查