简体中文 | 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.

⚠️ 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.

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

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

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

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)

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

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

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;

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

Submit Task API Request Example (Prompt Mode)

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
}

Query Progress API Response Example

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

Pay API Request and Response

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

Retry API Request Example

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

create_and_submit (Optional)

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

Return Value

Success:

json

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

Returns error message on failure.

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

giggle-generation-aimv

NPX Install

Tags

SKILL.md Content

MV Trustee Mode API Skill

⚠️ Review Before Installing

Required Setup Before First Use

Two Music Generation Modes

Shared Parameters (All Modes, Required)

Mode-Specific Parameters

Workflow Function

Function Signature

Parameter Extraction Rules

Examples

Submit Task API Request Example (Prompt Mode)

Query Progress API Response Example

Pay API Request and Response

Retry API Request Example

create_and_submit (Optional)

Return Value

Troubleshooting