30 秒 AIMV Trustee Mode（aimv-30）

与 giggle-generation-aimv 的流程完全相同：execute_workflow 一次、提交/轮询/支付/等待完成均一致。唯一区别：创建项目时 API type 为 aimv-30（30 秒 AIMV 产品线），不再是 mv。

⚠️ Review Before Installing

Please review before installing. This skill will:

1. Network – Calls Giggle.pro API for 30-second AIMV 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. On the main site, use the left sidebar → API Key (API 密钥) section to create or copy your key.

Configuration: Set system environment variable GIGGLE_API_KEY

• export GIGGLE_API_KEY=your_api_key

Verification steps:

1. Confirm the user has configured GIGGLE_API_KEY in system environment
2. If not configured, guide the user:

   Open giggle.pro while logged in → left sidebar → API Key / API 密钥 → copy your key, then run export GIGGLE_API_KEY=your_api_key in the terminal.

3. 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 (type: aimv-30) + submit task (merged) → poll progress (every 3 sec) → detect and pay pending items → wait for completion (max 1 hour).

Continuous progress updates (blocking MV workflow)

execute_workflow blocks for the full pipeline: create/submit (merged), poll (~every 3s), pay if needed, up to ~1 hour. You do not run shell --query yourself.

1. Before the call, tell the user the 30s AIMV job is running, that it usually takes minutes and can approach ~1 hour, and you will report when the function returns.
2. Invoke execute_workflow without waiting for the user to ask for a status check first.
3. After return, forward the full signed download_url / video_asset on success or the error payload in plain language; include project_id when useful for support or manual pay/query.
4. create_and_submit only: if they only want ids up front, use that path and query later when they ask.

Important:

• Never call create_project and submit_mv_task separately—always use execute_workflow or create_and_submit
• After calling, just wait for the function to return; all intermediate steps are automatic
• For non–30s or open-duration AIMV, use skill giggle-generation-aimv instead

Function Signature

execute_workflow(
    music_generate_type: str,      # Mode: prompt / custom / upload
    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 = "",
    # Upload mode
    music_asset_id: str = "",
)

Parameter Extraction Rules

1. 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.
2. scene_description: Default empty—only fill when the user explicitly mentions "scene", "visual description", or "visual style".
3. subtitle_enabled: 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:

api = MVTrusteeAPI()
result = api.execute_workflow(
    music_generate_type="prompt",
    aspect="16:9",
    project_name="My 30s 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 30s 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 30s 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 (unchanged from standard AIMV; project was created with type: aimv-30):

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

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

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

Do not strip response-content-disposition=attachment or other query params from the URL. 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:

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

Response:

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

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

api = MVTrusteeAPI()
r = api.create_and_submit(
    project_name="My 30s 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:

{
    "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	Re-copy the key from giggle.pro → left sidebar → API Key / API 密钥, then 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)	Generation took too long	Query progress manually with the project_id to check current status; contact support if the task is stuck