giggle-generation-aimv

MV 托管模式 API 技能

调用 MV 托管模式 API，运行完整的 MV 生成工作流。脚本将项目创建和任务提交合并为一个步骤——只调用一次 execute_workflow；切勿分别调用创建和提交。

⚠️ 安装前请先查看

安装前请先查看。 此技能将：

1. 网络 – 调用 Giggle.pro API 生成 MV

要求：python3 (>=3.6)、GIGGLE_API_KEY（系统环境变量）、pip 包：requests

出错时不要重试：如果脚本执行遇到错误，请勿重试。直接向用户报告错误并停止。

---

首次使用前的必要设置

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

API Key：登录 giggle.pro。在主站中，使用左侧边栏 → API Key（API 密钥）版块创建或复制密钥。

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

• export GIGGLE_API_KEY=your_api_key

验证步骤：

1. 确认用户已在系统环境中配置 GIGGLE_API_KEY
2. 如果尚未配置，请引导用户：

   登录后打开 giggle.pro → 左侧边栏 → API Key / API 密钥 → 复制密钥，然后在终端运行 export GIGGLE_API_KEY=your_api_key。

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

两种音乐生成模式

模式	music_generate_type	必需参数	说明
提示词	prompt	prompt, vocal_gender	用文字描述音乐
自定义	custom	lyrics, style, title	提供歌词、风格和标题

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

• 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：音乐描述（必需）
• vocal_gender：人声性别 — male / female / auto（可选，默认为 auto）
• instrumental：仅器乐（可选，默认为 false）

自定义模式：

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

工作流函数

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

连续进度更新（阻塞式 MV 工作流）

execute_workflow 会阻塞，直至整个 MV 流程完成：创建/提交（合并）、轮询（约每 3 秒一次）、必要时付款，最长约 1 小时。无需自行运行 shell --query。

1. 调用前，告知用户 MV 任务正在运行，通常需要几分钟，最长可能接近 1 小时，并说明将在函数返回后告知用户。
2. 调用 execute_workflow，不要等用户先询问状态。
3. 返回后，成功时转发完整的签名版 download_url / video_asset；失败时用通俗语言说明错误载荷。如有助于支持处理或手动付款/查询，请附上 project_id。
4. 仅限 create_and_submit：如果用户只想先获取 ID，请使用该路径，并在用户询问时再查询。

重要：

• 切勿分别调用 create_project 和 submit_mv_task——始终使用 execute_workflow 或 create_and_submit
• 调用后只需等待函数返回；所有中间步骤均会自动完成

函数签名

execute_workflow(
    music_generate_type: str,      # Mode: prompt / custom
    aspect: str,                    # Aspect ratio: 16:9 or 9:16
    project_name: str,              # Project name
    reference_image: str = "",      # Reference image asset_id (mutually exclusive with reference_image_url)
    reference_image_url: str = "",  # Reference image URL or base64 (mutually exclusive with reference_image)
    scene_description: str = "",    # Scene description, default empty
    subtitle_enabled: bool = False, # Subtitle toggle, default False
    # Prompt mode
    prompt: str = "",
    vocal_gender: str = "auto",
    instrumental: bool = False,
    # Custom mode
    lyrics: str = "",
    style: str = "",
    title: str = "",
)

参数提取规则

1. reference_image 和 reference_image_url：至少需要提供一个。对于 asset_id，使用 reference_image；对于图片 URL 或 base64，使用 reference_image_url。
2. scene_description：默认为空——仅当用户明确提到“场景”“视觉描述”或“视觉风格”时才填写。
3. subtitle_enabled：默认为 False——仅当用户明确要求字幕时才设为 True。
4. aspect：用户提到 portrait/vertical/9:16 时使用 9:16；否则默认为 16:9。
5. 模式选择：“描述音乐 / 使用提示词” → prompt；“这是我的歌词 / 歌词如下” → custom；

示例

提示词模式：

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"
)

自定义模式（用户提供歌词）：

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 请求示例（提示词模式）

提交端点（/api/v1/trustee_mode/mv/submit）的请求体：

{
  "project_id": "<your-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）不能同时使用。

自定义模式：

{
  "project_id": "<your-project-id>",
  "music_generate_type": "custom",
  "lyrics": "Verse 1:\nStanding by the sea watching the sunset\nMemories rush in like waves\n\nChorus:\nLet the sea breeze blow away all worries\nIn this golden moment\nWe found each other\n",
  "style": "pop ballad",
  "title": "Seaside Memories",
  "reference_image": "<asset_id>",
  "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": "<response-uuid>",
  "data": {
    "project_id": "<your-project-id>",
    "video_asset": {
      "asset_id": "<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 中删除 response-content-disposition=attachment 或其他查询参数。错误格式（仅未签名 URL）：

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

付款 API 请求与响应

付款端点（/api/v1/trustee_mode/mv/pay）：

请求体：

{
  "project_id": "<your-project-id>"
}

响应：

{
  "code": 200,
  "msg": "success",
  "uuid": "<response-uuid>",
  "data": {
    "order_id": "<order-id>",
    "price": 580
  }
}

重试 API 请求示例

当某个步骤失败时，请引导用户调用重试端点，从该步骤继续：

{
  "project_id": "<your-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"
)
# Returns project_id for manual query/pay later

返回值

成功：

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

失败时返回错误消息。

故障排查

场景	原因	解决方案
401 Unauthorized 或“invalid API key”	GIGGLE_API_KEY 缺失、已过期或不正确	从 giggle.pro → 左侧边栏 → API Key / API 密钥 重新复制密钥，然后重新导出：export GIGGLE_API_KEY=your_api_key
429 Too Many Requests	超出 API 速率限制	等待几分钟后重试；避免在短时间内连续提交多个项目
网络超时 / 连接错误	网络不稳定或 API 服务暂时不可用	脚本会自动重试，最多 5 次，每次间隔 5 秒；如果仍然失败，请检查网络
pay_status: pending	项目需要先付款才能继续	工作流函数会自动处理此情况；如果手动运行，请使用 project_id 调用付款接口
任务步骤失败（status: failed）	生成步骤（例如 music-generate、shot）遇到错误	使用重试接口：{"project_id": "<your-project-id>", "current_step": "<failed-step>"}，从失败的步骤继续
工作流超时（超过 1 小时）	MV 生成耗时过长	使用 project_id 手动查询进度，检查当前状态；如果任务卡住，请联系支持团队