giggle-generation-aimv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

简体中文 | English

MV Trustee Mode API Skill

Calls the MV trustee mode API to run the full MV generation workflow. Project creation and task submission are merged into one step in the script—call

execute_workflow

once only; never call create and submit separately.

调用MV trustee mode API以运行完整的MV生成工作流。脚本中将项目创建与任务提交合并为一步——只需调用一次

execute_workflow

；切勿分别调用创建和提交操作。

⚠️ Review Before Installing

⚠️ 安装前须知

Please review before installing. This skill will:

Network – Calls Giggle.pro API for MV generation

Requirements:

python3 (>=3.6)

GIGGLE_API_KEY

(system environment variable), pip packages:

requests

No Retry on Error: If script execution encounters an error, do not retry. Report the error to the user directly and stop.

请在安装前仔细阅读。 本技能将：

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

要求：

python3 (>=3.6)

、

GIGGLE_API_KEY

（系统环境变量）、pip包：

requests

错误时请勿重试：若脚本执行遇到错误，请勿重试。直接向用户报告错误并停止操作。

Required Setup Before First Use

首次使用前的必要配置

Before performing any operation, confirm the user has configured the API Key.

API Key: Log in to Giggle.pro and obtain the API Key from account settings.

Configuration: Set system environment variable

GIGGLE_API_KEY

```
export GIGGLE_API_KEY=your_api_key
```

Verification steps:

Confirm the user has configured
```
GIGGLE_API_KEY
```
in system environment
If not configured, guide the user:
Hello! Before using the MV generation feature, you need to configure the API Key. Please go to Giggle.pro to get your API Key, then run
```
export GIGGLE_API_KEY=your_api_key
```
in the terminal.
Wait for the user to configure before continuing the workflow

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

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

配置：设置系统环境变量

GIGGLE_API_KEY

```
export GIGGLE_API_KEY=your_api_key
```

验证步骤:

确认用户已在系统环境中配置
```
GIGGLE_API_KEY
```
若未配置，引导用户:
您好！在使用MV生成功能前，您需要配置API Key。请前往Giggle.pro获取您的API Key，然后在终端中运行
```
export GIGGLE_API_KEY=your_api_key
```
。
等待用户完成配置后再继续工作流

Two Music Generation Modes

两种音乐生成模式

Mode	music_generate_type	Required params	Description
Prompt	`prompt`	prompt, vocal_gender	Describe music in text
Custom	`custom`	lyrics, style, title	Provide lyrics, style, and title

模式	music_generate_type	必填参数	描述
提示词模式	`prompt`	prompt, vocal_gender	通过文本描述音乐
自定义模式	`custom`	lyrics, style, title	提供歌词、风格和标题

Shared Parameters (All Modes, Required)

通用参数（所有模式，必填）

reference_image or reference_image_url: Reference image—provide at least one (asset_id or download URL). Also supports base64 image, e.g.
```
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
```
. For base64: pass the raw Base64 string directly; do not add the data:image/xxx;base64 prefix.
aspect: Aspect ratio,
```
16:9
```
or
```
9:16
```
scene_description: Visual scene description, default empty—only set when the user explicitly mentions the scene (max 200 chars)
subtitle_enabled: Enable subtitles, default false

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

Mode-Specific Parameters

模式专属参数

Prompt mode:

```
prompt
```
: Music description (required)
```
vocal_gender
```
: Vocal gender —
```
male
```
/
```
female
```
/
```
auto
```
(optional, default
```
auto
```
)
```
instrumental
```
: Instrumental only (optional, default false)

Custom mode:

```
lyrics
```
: Lyrics content (required)
```
style
```
: Music style (required)
```
title
```
: Song title (required)

提示词模式:

```
prompt
```
: 音乐描述（必填）
```
vocal_gender
```
: 人声性别 —
```
male
```
/
```
female
```
/
```
auto
```
（可选，默认
```
auto
```
）
```
instrumental
```
: 仅纯音乐（可选，默认false）

自定义模式:

```
lyrics
```
: 歌词内容（必填）
```
style
```
: 音乐风格（必填）
```
title
```
: 歌曲标题（必填）

Workflow Function

工作流函数

Use

execute_workflow

to run the full workflow—call once and wait. Internally: create project + submit task (merged) → poll progress (every 3 sec) → detect and pay pending items → wait for completion (max 1 hour).

Important:

Never call

create_project

and

submit_mv_task

separately—always use

execute_workflow

create_and_submit

After calling, just wait for the function to return; all intermediate steps are automatic

使用

execute_workflow

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

重要提示:

切勿分别调用

create_project

和

submit_mv_task

——请始终使用

execute_workflow

或

create_and_submit

调用后只需等待函数返回；所有中间步骤均自动完成

Function Signature

函数签名

python

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

python

execute_workflow(
    music_generate_type: str,      # 模式: prompt / custom
    aspect: str,                    # 宽高比: 16:9 or 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 = "",
)

Parameter Extraction Rules

参数提取规则

reference_image and reference_image_url: At least one required. Use
```
reference_image
```
for asset_id; use
```
reference_image_url
```
for image URL or base64.
scene_description: Default empty—only fill when the user explicitly mentions "scene", "visual description", or "visual style".
subtitle_enabled: Default False—only set True when the user explicitly requests subtitles.
aspect: Use
```
9:16
```
when the user mentions portrait/vertical/9:16; otherwise default
```
16:9
```
.
Mode selection: "Describe music / use prompt" → prompt; "Here are my lyrics / lyrics are" → custom;

reference_image和reference_image_url：至少必填一项。asset_id使用
```
reference_image
```
；图片URL或base64使用
```
reference_image_url
```
。
scene_description：默认为空——仅当用户明确提及“场景”、“视觉描述”或“视觉风格”时才填写。
subtitle_enabled：默认False——仅当用户明确要求字幕时才设置为True。
aspect：当用户提到竖屏/垂直/9:16时使用
```
9:16
```
；否则默认
```
16:9
```
。
模式选择：“描述音乐/使用提示词”→提示词模式；“这是我的歌词/歌词如下”→自定义模式；

Examples

示例

Prompt mode:

python

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 mode (user provides lyrics):

python

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

With scene description (when user explicitly describes the scene):

python

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

提示词模式:

python

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

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

python

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

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

python

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

Submit Task API Request Example (Prompt Mode)

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

Submit endpoint (

/api/v1/trustee_mode/mv/submit

) request body:

json

{
  "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
}

Note:

reference_image

(asset_id) and

reference_image_url

(URL or base64) are mutually exclusive.

Custom mode:

json

{
  "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/v1/trustee_mode/mv/submit

）请求体：

json

{
  "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）不可同时使用。

自定义模式:

json

{
  "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
}

Query Progress API Response Example

查询进度API响应示例

Query endpoint (

/api/v1/trustee_mode/mv/query

) response (all steps completed):

json

{
  "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": [...]
  }
}

Note: When

pay_status

pending

, call the pay endpoint. When all

steps

are done,

video_asset.download_url

will have a value—return the full signed URL. Correct format:

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

Wrong (unsigned URL only):

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

查询接口（

/api/v1/trustee_mode/mv/query

）响应（所有步骤完成）：

json

{
  "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）：

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

Pay API Request and Response

支付API请求与响应

Pay endpoint (

/api/v1/trustee_mode/mv/pay

Request body:

json

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

Response:

json

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

支付接口（

/api/v1/trustee_mode/mv/pay

）：

请求体:

json

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

响应:

json

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

Retry API Request Example

重试API请求示例

When a step fails, guide the user to call the retry endpoint to resume from that step:

json

{
  "project_id": "<your-project-id>",
  "current_step": "shot"
}

Note:

current_step

is the step name to retry (e.g.

music-generate

storyboard

shot

editor

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

json

{
  "project_id": "<your-project-id>",
  "current_step": "shot"
}

注意：

current_step

是要重试的步骤名称（例如

music-generate

、

storyboard

、

shot

、

editor

）。

create_and_submit (Optional)

create_and_submit（可选）

If you only need to create the project and submit the task without waiting for completion, use

create_and_submit

. Never call

create_project

and

submit_mv_task

separately:

python

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

如果您仅需要创建项目并提交任务，无需等待完成，请使用

create_and_submit

。切勿分别调用

create_project

和

submit_mv_task

：

python

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

返回project_id用于后续手动查询/支付

undefined

undefined

Return Value

返回值

Success:

json

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

Returns error message on failure.

成功时：

json

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

失败时返回错误信息。

Troubleshooting

故障排除

Scenario	Cause	Solution
`401 Unauthorized` or "invalid API key"	`GIGGLE_API_KEY` is missing, expired, or incorrect	Verify the key at Giggle.pro account settings and re-export: `export GIGGLE_API_KEY=your_api_key`
`429 Too Many Requests`	API rate limit exceeded	Wait a few minutes and retry; avoid submitting multiple projects in rapid succession
Network timeout / connection error	Unstable network or API service temporarily unavailable	The script auto-retries up to 5 times with 5-second intervals; check your network if it still fails
`pay_status: pending`	The project requires payment before proceeding	The workflow function handles this automatically; if running manually, call the pay endpoint with the `project_id`
Task step failed ( `status: failed` )	A generation step (e.g. `music-generate` , `shot` ) encountered an error	Use the retry endpoint: `{"project_id": "<your-project-id>", "current_step": "<failed-step>"}` to resume from the failed step
Workflow timeout (> 1 hour)	MV generation took too long	Query progress manually with the `project_id` to check current status; contact support if the task is stuck

场景	原因	解决方案
`401 Unauthorized` 或"invalid API key"	`GIGGLE_API_KEY` 缺失、过期或不正确	在Giggle.pro账户设置中验证密钥，重新执行导出命令： `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` 手动查询进度；若任务卡住请联系支持人员