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

1. 1. Network – Calls Giggle.pro API for MV generation

Requirements: python3 (>=3.6), GIGGLE_API_KEY (system environment variable), pip packages: INLINECODE3

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

• - INLINECODE5

Verification steps:

1. 1. Confirm the user has configured GIGGLE_API_KEY in system environment
2. 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.

1. 3. Wait for the user to configure before continuing the workflow

Two Music Generation Modes

Mode	musicgeneratetype	Required params	Description
Prompt	INLINECODE8	prompt, vocal_gender	Describe music in text
Custom

custom | lyrics, style, title | Provide lyrics, style, and title |

Shared Parameters (All Modes, Required)

• - referenceimage or referenceimageurl: Reference image—provide at least one (assetid 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 INLINECODE12
• scenedescription: Visual scene description, default empty—only set when the user explicitly mentions the scene (max 200 chars)
• subtitleenabled: Enable subtitles, default false

Mode-Specific Parameters

Prompt mode:

• - prompt: Music description (required)
• INLINECODE14: Vocal gender — male / female / auto (optional, default auto)
• INLINECODE19: Instrumental only (optional, default false)

Custom mode:

• - lyrics: Lyrics content (required)
• INLINECODE21: Music style (required)
• INLINECODE22: 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 or INLINECODE27
• After calling, just wait for the function to return; all intermediate steps are automatic

Function Signature

CODEBLOCK0

Parameter Extraction Rules

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

Examples

Prompt mode:
CODEBLOCK1

Custom mode (user provides lyrics):
CODEBLOCK2

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

Submit Task API Request Example (Prompt Mode)

Submit endpoint (/api/v1/trustee_mode/mv/submit) request body:

CODEBLOCK4

Note: reference_image (asset_id) and reference_image_url (URL or base64) are mutually exclusive.

Custom mode:

CODEBLOCK5

Query Progress API Response Example

Query endpoint (/api/v1/trustee_mode/mv/query) response (all steps completed):

CODEBLOCK6

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:

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

Wrong (unsigned URL only):
CODEBLOCK8

Pay API Request and Response

Pay endpoint (/api/v1/trustee_mode/mv/pay):

Request body:
CODEBLOCK9

Response:
CODEBLOCK10

Retry API Request Example

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

CODEBLOCK11

Note: current_step is the step name to retry (e.g. music-generate, storyboard, shot, editor).

createandsubmit (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:

CODEBLOCK12

Return Value

Success:
CODEBLOCK13

Returns error message on failure.

Troubleshooting

Scenario	Cause	Solution
INLINECODE49 or "invalid API key"	INLINECODE50 is missing, expired, or incorrect	Verify the key at Giggle.pro account settings and re-export: INLINECODE51
INLINECODE52

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 |