Use when the user wants to create AI music videos (MV)—including generating music from text prompts or using custom lyrics. Triggers: generate MV, music video, make video for this song, lyrics video, create MV, AI music video, music+video, generate video from lyrics.
简体中文 | English
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.
Please review before installing. This skill will:
Requirements: python3, GIGGLE_API_KEY (system environment variable), pip packages: requests
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_keyVerification steps:
GIGGLE_API_KEY in system environmentHello! 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_keyin the terminal.
| 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 |
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==". For base64: pass the raw Base64 string directly; do not add the data:image/xxx;base64 prefix.16:9 or 9:16Prompt 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)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:
create_project and submit_mv_task separately—always use execute_workflow or create_and_submitexecute_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 = "",
)
reference_image for asset_id; use reference_image_url for image URL or base64.9:16 when the user mentions portrait/vertical/9:16; otherwise default 16:9.Prompt mode:
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):
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):
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 endpoint (/api/v1/trustee_mode/mv/submit) request body:
{
"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
}
Note: reference_image (asset_id) and reference_image_url (URL or base64) are mutually exclusive.
Custom mode:
{
"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
}
Query endpoint (/api/v1/trustee_mode/mv/query) response (all steps completed):
{
"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": [...]
}
}
Note: When pay_status is 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: