# Giggle Generation Aimv

> 当用户希望创建 AI 音乐视频（MV）时使用此技能——包括根据文字提示生成音乐或使用自定义歌词。触发词：生成 MV、音乐视频、为这首歌做视频、歌词视频、创建 MV、AI 音乐视频、音乐+视频、根据歌词生成视频。

- Skill: `dvcrn/giggle-generation-aimv` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dvcrn/giggle-generation-aimv`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/giggle-generation-aimv/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/giggle-generation-aimv

---


# MV Trustee 模式 API 技能

调用 MV trustee 模式 API 运行完整 MV 生成工作流。**项目创建与任务提交在脚本内合并为一步**——只需调用一次 `execute_workflow`；切勿分开调用 create 和 submit。

## 首次使用前的配置（必选）

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

**API Key**：登录 [Giggle.pro](https://giggle.pro/) 并在账号设置中获取 API Key。

配置方式（任选其一）：
1. **项目根目录 `.env`**：复制 `env.example` 为 `.env`，并设置 `GIGGLE_API_KEY=your_api_key`
2. **环境变量**：`export GIGGLE_API_KEY=your_api_key`

**检查步骤**：
1. 确认用户已在 `.env` 或环境变量中配置 `GIGGLE_API_KEY`
2. 若未配置，**提示用户**：
   > 你好！在使用 MV 生成功能前，需要先配置 API Key。请前往 [Giggle.pro](https://giggle.pro/) 获取 API Key，然后在项目根目录创建 `.env` 文件（参考 `env.example`），添加 `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 小时）。

**重要**：
- 切勿分别调用 `create_project` 和 `submit_mv_task`——始终使用 `execute_workflow` 或 `create_and_submit`
- 调用后只需等待函数返回；所有中间步骤均自动处理

### 函数签名

```python
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: str = "",
    vocal_gender: str = "auto",
    instrumental: bool = False,
    # 自定义模式
    lyrics: str = "",
    style: str = "",
    title: str = "",
)
```

### 参数提取规则

1. **reference_image 与 reference_image_url**：至少需要其一。asset_id 用 `reference_image`，图片链接或 base64 用 `reference_image_url`。
2. **scene_description**：默认空——仅当用户明确提及「场景」「视觉描述」或「视觉风格」时填写。
3. **subtitle_enabled**：默认 False——仅当用户明确要求字幕时设为 True。
4. **aspect**：用户提及竖屏/垂直/9:16 时用 `9:16`；否则默认 `16:9`。
5. **模式选择**：「描述音乐 / 用提示」→ prompt；「这是我的歌词 / 歌词是」→ custom；

### 示例

**提示模式**：
```python
api = MVTrusteeAPI()
result = api.execute_workflow(
    music_generate_type="prompt",
    aspect="16:9",
    project_name="我的 MV",
    reference_image_url="https://example.com/ref.jpg",
    prompt="轻快流行乐，阳光海滩氛围",
    vocal_gender="female"
)
```

**自定义模式（用户提供歌词）**：
```python
result = api.execute_workflow(
    music_generate_type="custom",
    aspect="9:16",
    project_name="歌词 MV",
    reference_image="asset_xxx",
    lyrics="Verse 1: 春风拂面...",
    style="pop",
    title="春歌"
)
```

**带场景描述**（当用户明确描述场景时）：
```python
result = api.execute_workflow(
    music_generate_type="prompt",
    aspect="16:9",
    project_name="场景 MV",
    reference_image_url="https://...",
    prompt="电子舞曲",
    scene_description="城市夜景，霓虹闪烁，车流涌动"
)
```

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

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

```json
{
  "project_id": "c0cb1f32-bb07-4449-add5-e42ccfca1ab6",
  "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`（链接或 base64）二选一，互斥。

**自定义模式**：

```json
{
  "project_id": "0ea74500-9178-4693-b581-342d5e17994c",
  "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": "is45gnvumgd",
  "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`）响应（所有步骤已完成）：

```json
{
  "code": 200,
  "msg": "success",
  "uuid": "24052352-f231-495a-9581-3827c4eb0bdf",
  "data": {
    "project_id": "65cf262d-c4b1-4733-abf1-ec6a7bdb944a",
    "video_asset": {
      "asset_id": "ryco1asdmb",
      "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。正确返回格式：
```json
https://assets.giggle.pro/private/ai_director/348e4956c7bd4f763b/qzjc7gwkpf.mp4?Policy=...&Key-Pair-Id=...&Signature=...&response-content-disposition=attachment
```
错误（仅未签名 URL）：
```json
https://assets.giggle.pro/private/ai_director/348e4956c7bd4f763b/qzjc7gwkpf.mp4
```

### 支付 API 请求与响应

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

**请求体**：
```json
{
  "project_id": "28b4f4f7-d219-4754-a78b-d9896cd16573"
}
```

**响应**：
```json
{
  "code": 200,
  "msg": "success",
  "uuid": "1440ba5f-ba1c-41f6-a92c-53337a7df1c2",
  "data": {
    "order_id": "2a93f1c1-9e4d-4d29-89d7-15deea4e3732",
    "price": 580
  }
}
```

### 重试 API 请求示例

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

```json
{
  "project_id": "28b4f4f7-d219-4754-a78b-d9896cd16573",
  "current_step": "shot"
}
```

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

### create_and_submit（可选）

若仅需创建项目并提交任务，不等待完成，可使用 `create_and_submit`。**切勿**分别调用 `create_project` 和 `submit_mv_task`：

```python
api = MVTrusteeAPI()
r = api.create_and_submit(
    project_name="我的 MV",
    music_generate_type="prompt",
    aspect="16:9",
    reference_image_url="https://...",
    prompt="轻快流行乐"
)
# 返回 project_id，供后续手动查询/支付
```

### 返回值

成功：
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "project_id": "...",
        "download_url": "https://...",
        "video_asset": {...},
        "status": "completed"
    }
}
```

失败时返回错误信息。