Source: giggle-official/skills · API: giggle.pro · Script: scripts/generation_api.py
This skill = Giggle API finished video（scripts/generation_api.py）+ MiniMax-H3 prompt engineering resource library（references/、prompts/）。
- Main workflow: optimize prompt → API Key → use
text/image/omnito submit and poll the result. - In-depth writing: for creative hooks, storyboard templates, long-video pipelines, word lists, and examples, see the resource index.
In-repo resource index
| Path | Purpose |
|---|---|
| references/prompt-engineering.md | Prompt engineering spec: 10 major capabilities, 4 structural templates, interaction flow, quality self-check |
| references/creative-strategy.md | What to write, ≤15s and long-form creative strategy |
| references/production-pipeline.md | Long-video pre-production pipeline (character→storyboard→generation→stitching) |
| references/long-video-strategy.md | Segmentation, extension, transitions, locked statements, output templates |
| references/examples.md | Scenarios and multimodal examples (10 major capability categories) |
| references/vocabulary.md | Camera movement, image quality, atmospheric effects vocabulary |
| references/image-generation.md | Character reference image / first-frame image pre-generation spec |
| prompts/ | Theme expansion packs, OpenClaw full-case short essays |
⚠️ Platform and API constraints (Giggle prevails)
The resource library contains general MiniMax-H3 prompt best practices;video and multimodal finished videos are submitted only via giggle.pro. When actually calling this repo's scripts, follow the table below:
| Item | Giggle (this script) |
|---|---|
| Language | Consistent withthe user's input language(see the Language Rule section below); Chinese templates in the resources may be used for structure |
| Duration | 3–15 integer seconds,--duration |
| Aspect ratio / resolution | --aspect-ratio、--resolution |
| omni images | at most 9 images,url: or base64: |
| reference audio / video | only url:，--audios、--videos |
In the prompt, @图片N / @视频N |
only the numbering convention; must be passed via CLIcorresponding to a real URL, andallreferences must be passed |
If the resources say "mixed materials ≤12" and this conflicts with Giggle's limit,take the stricter side(especially images ≤9).
@引用 → Giggle CLI（omni）
| Prompt convention | Map to |
|---|---|
@图片1 … @图片N |
--images "url:..."(in numbered order; multiple parameters or multiple --imagesare allowed; the script will merge them) |
@视频1 … |
--videos "url:..." |
@音频1 … |
--audios "url:..." |
⚠️ Language Rule — MUST FOLLOW
Match the user's input language exactly. Never translate. Never output a second language version.
- User writes in Chinese → optimize in Chinese → pass Chinese prompt to API
- User writes in English → optimize in English → pass English prompt to API
- Output ONE version of the optimized prompt. No bilingual display. No "API submission version".
(The resource library contains many Chinese examples: borrow onlythe structure and organization; the output language still follows the rules above.)
Step 1: Prompt optimization (must be completed before proceeding to Step 2)
User input often describes things inaccurately.The following complete optimization process must be completed first to generate a high-quality prompt, and only after user confirmation may it be submitted to the API.
For the complete spec, see references/prompt-engineering.md; the following is the inline execution summary in SKILL.md.
MiniMax-H3 Core Capabilities Quick Reference
| # | Capability | Prompt core pattern |
|---|---|---|
| 1 | Consistency control | [角色]@图片N + [动作/剧情] + [场景]@图片N |
| 2 | Camera movement/action replication | 参考@视频1的[运镜/动作/节奏] + [主体]@图片N |
| 3 | Creative/effects replication | 参考@视频1的[特效/转场] + 将[元素]替换为@图片N |
| 4 | Plot completion | [分镜脚本] + [演绎方式] + [音效/台词] |
| 5 | Video extension | 将@视频1延长Xs + [新增内容] |
| 6 | Voice Control | [画面] + 音色参考@视频1 + "台词" |
| 7 | One-Shot Sequence | 一镜到底 + @图片1@图片2... + 全程不切镜头 |
| 8 | Video Editing | 将@视频1中的[A]换成@图片1 + [修改说明] |
| 9 | Music Beat Sync | @图片1...@图片N + 参考@视频1的画面节奏/卡点 |
| 10 | Emotional Performance | [角色] + [情绪变化描述] + [运镜配合] |
For detailed examples of each capability, see references/examples.md。
Phase 0: Determine Content Type (the most critical step)
| Scenario | Path | Core Task |
|---|---|---|
| ≤15 seconds | Path A | Help the user find asingle visual hook with viral potential; refer to creative-strategy.md viral pattern library |
| >15 seconds | Path B | Run the complete pre-production pipeline: character design → character card image prompts → storyboard script → first-frame image prompts → per-shot video prompts; refer to production-pipeline.md |
Phase 1: Get User's Idea
The user describes the content they want to generate.
Phase 2: Confirm Key Parameters (skip if already specified)
- Duration: Short 3–8s / Medium 9–12s / Long 13–15s / Extra-long >15s
- Aspect Ratio: Landscape 16:9 / Portrait 9:16 / Square 1:1
- Assets: Text only / with images / with images + video / all modalities
- Additional Preferences(optional): emotional atmosphere, camera style, intended use scenario
Phase 3: Generate Optimized Prompts (for ≤15 seconds, output 2–3 versions; for >15 seconds, output according to the pipeline)
Prompt Structure Quick Reference:
| Scenario | Recommended Structure |
|---|---|
| ≤12 seconds | [风格总纲]，[主体]，[动作]，[环境/光影]，[运镜]，[音效] |
| 13–15 seconds | Timestamp storyboard method (describe segment by segment: 0-3s / 4-8s / 9-12s / 13-15s) |
| Short Drama Dialogue | Visuals + dialogue (character/emotion annotations) + separate sound effects |
| Epic Production | Quality anchoring + grand and coherent statement + segment by segment + three layers of lighting + closing sentence |
Camera Movement Three-Tier Quick Reference:
- Basic Actions：Pan / Dolly / Zoom / Crane / Orbit / Tracking
- Modifiers：Smooth / Slow / Fast / Cinematic / Dreamy / Handheld / Aerial
- Combination Moves: at most 2–3 at a time, connected with
+; lens texture terms such as "fog particles sticking to the lens" can greatly enhance immersion
Image Style Matching (when generating character reference images / first-frame images):
| Genre | Recommended Image Generation Style |
|---|---|
| Xianxia / Cultivation | 3D Chinese animation rendering, Chinese xianxia concept design |
| Ancient Style / Historical | Chinese-style gongbi painting, ink wash painting |
| Cyberpunk / Sci-Fi | Futuristic sci-fi realistic CG, concept design |
| Realistic / People | Cinematic photographic realism, portrait photography |
| Food / Products | Food advertising photography, commercial photography |
| Anime (Japanese) | Cel-shaded style |
| Anime (Chinese) | 3D Chinese animation rendering |
Character reference image format:9:16竖版构图。[风格锚定]角色设定图，[构图视角]，角色居中。[面部7要素]。[发型]。[服装逐件+新旧状态]。[道具]。[体态气质]。[光影]。禁止：任何文字、字幕、LOGO、水印
First-frame image format:[画幅比]。[风格锚定]，[构图+角色位置]。[角色状态+关键辨识特征]。[环境细节]。[光影层次]。[色调氛围]。禁止：任何文字、字幕、LOGO、水印
@Reference Number Assignment Rules:
- Shared Assets(such as character reference images shared across versions) are numbered sequentially starting from
@图片1Start numbering sequentially - Version-Specific Assets(first-frame image, last-frame image for each version) increment after the public asset numbering
- Label the purpose of each asset, clearly stating whether it is "reference" (borrowing style/motion) or "edit" (modifying the original asset)
Multimodal combination techniques:
- Has a first-frame image + wants to reference video motion →
@图片1为首帧，参考@视频1的打斗动作 - Fuse multiple videos →
在@视频1和@视频2之间加一个场景，内容为xxx - No audio asset → directly reference the sound in the video, no need to upload audio separately
- Continuous motion →
角色从跳跃直接过渡到翻滚，保持动作连贯流畅 - When there are multiple assets, be sure to check whether each @object is clearly labeled; don't mix up images, videos, and characters
≤15-second output format (full mode):
## 视频提示词
**主题**：[一句话概括]
**时长**：[X秒] | **比例**：[16:9 / 9:16 / 1:1]
### 公共参考素材（如有）
- @图片1：[用途说明 + 图片生成提示词]
---
### 版本一：[版本标题]
#### 提示词
[完整提示词]
#### 参考素材
- 首帧 @图片N：[描述 + 图片生成提示词]
---
### 版本二：[版本标题]
[同上结构]
---
### 提示词解析
[各版本设计意图差异]
For the 15-second output format, see references/long-video-strategy.md(including global lock statements, unified negative prompts, and segmented templates).
In-depth resource index:
| Requirement | Reference file |
|---|---|
| Viral concept, first 2-second hook | creative-strategy.md |
| Long-video segmentation, transitions, pipeline | production-pipeline.md、long-video-strategy.md |
| Camera movement vocabulary, quality anchor words | vocabulary.md |
| Multimodal scene templates | examples.md |
| Character reference image / first-frame image specifications | image-generation.md |
| Theme expansion pack, full short-drama plan | prompts/ |
Phase 4: User confirmation
The user selects a version (may request adjustments: style/color tone/camera movement/dialogue/duration); after confirming the final version, proceed to Step 2.
Giggle override rules (take precedence over prompt-engineering.md)
- : Strictly follow the Language Rule. User in Chinese → Chinese prompt; user in English → English prompt. "Output ONE version" means bilingual side-by-side output is prohibited, not that the number of versions is limited.: Strictly follow the Language Rule. User in Chinese → Chinese prompt; user in English → English prompt. "Output ONE version" means bilingual side-by-side output is prohibited, not that the number of versions is limited.
- : For the general prompt methods in references, the Giggle constraints of MiniMax-H3 in this file (duration 3–15s, images ≤9, @reference naming, etc.) shall prevail.: For the general prompt methods in references, the Giggle constraints of MiniMax-H3 in this file (duration 3–15s, images ≤9, @reference naming, etc.) shall prevail.
- : If the user provides multiple images/videos/audio, when optimizing the prompt you must explain the purpose of each reference one by one; when submitting in Step 3, all of them must be passed to the CLI, not just the first one.: If the user provides multiple images/videos/audio, when optimizing the prompt you must explain the purpose of each reference one by one; when submitting in Step 3, all of them must be passed to the CLI, not just the first one.
Step 1 deliverables
- The user's selectedoneoptimized prompt (consistent with the user's language, having passed quality self-check)
- Omni: each reference in the prompt has a corresponding URL, and the numbering mapping (
@图片Netc.) has been completed - Extra-long video: the number of segments and transition points have been determined according to long-video-strategy.md the number of segments and transition points have been determined
Step 2: API Key Setup (One-Time)
python3 scripts/generation_api.py --check-key
Configuredthen proceed to Step 3;Not configuredthen ask the user for the Key and execute:
python3 scripts/generation_api.py --setup --api-key <key>
Step 3: Generate Video
Text-to-Video:
python3 scripts/generation_api.py \
--mode text --prompt "<optimized_prompt>" \
--model MiniMax-H3 --duration 4 --aspect-ratio 16:9 --resolution 480p
Image-to-Video:
python3 scripts/generation_api.py \
--mode image --prompt "<optimized_prompt>" \
--start-frame "url:<URL>" --model MiniMax-H3 --duration 4
Omni:
- Multiple reference assets: From the conversation, collect all reference image / reference video / reference audio URLs provided by the user (including the
url:prefix), then call the CLI once with all of them. The same option may be followed by multiple space-separated arguments (e.g.,--images "url:a" "url:b"); you may also multiple times write the same option (e.g., two lines of--images), and the script will merge them into a complete list. It is prohibited to submit only the first link. - Quantity: Images total at most 9 (API validation); audio and video are all passed in according to the actual number of items in the conversation.
# 示例：多图 + 多音频 + 多参考视频（按实际数量增删参数）
python3 scripts/generation_api.py \
--mode omni --prompt "<optimized_prompt>" \
--images "url:<img1>" "url:<img2>" \
--audios "url:<audio1>" "url:<audio2>" \
--videos "url:<ref_video1>" "url:<ref_video2>" \
--model MiniMax-H3 --duration 4
If a certain type of reference is not provided, the corresponding option may be omitted (but at least keep --images、--audios、--videos one of them).
After submission: By default, the script polls about once every 10 seconds (up to about 10 minutes); after the task is complete,proactivelypush the result (including the link) to the user without waiting for the user to follow up.
Parameters
| Parameter | Default | Options |
|---|---|---|
--mode |
required | text / image / omni |
--prompt |
required | Max 10,000 chars — use user's input language |
--model |
MiniMax-H3 |
MiniMax-H3 |
--duration |
4 |
3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 seconds |
--aspect-ratio |
16:9 |
1:1 / 9:16 / 16:9 / 4:3 / 3:4 |
--resolution |
480p |
480p / 768p |
--generating-count |
1 |
1–4 |
--images |
— | omni：url: or base64:, can be repeated multiple times; up to 9 images |
--audios |
— | omni: only url:, can be repeated multiple times |
--videos |
— | omni: reference video, only url:, can be repeated multiple times |
Quality self-check (before submission)
Prompt quality (check after Phase 3 generation)
- @reference numbers correspond one-to-one with the asset list; public assets are numbered first
- total number of files ≤ 12 (images + videos + audio combined); omni images ≤ 9
- does not include realistic human face assets
- the 13–15 second video uses timestamped shot breakdowns, covering the full duration with no omissions
- dialogue is wrapped in quotation marks and labeled with character and emotion
- sound effect descriptions and visual descriptions are written separately
- each segment of an ultra-long video includes style lock, character lock, and scene lock statements
- the beginning of the extension segment of an ultra-long video already has a bridge shot or tail-frame continuation micro-motion arranged
- the unified negative prompt already covers style drift, character face changes, color cast, sudden lighting changes, watermarks
- the character reference image aspect ratio is 9:16 vertical; the first-frame image aspect ratio matches the video
API submission (check before executing Step 3)
- the prompt language matches the user input language; no bilingual comparison
-
duration ∈ [3,15](integer) - omni: each audio / video starts with
url:at the beginning; base64 is limited to images only - user-provided reference URL allappear in the CLI, with no omissions
- the ultra-long narrative has been split into segments according to long-video-strategy.md , and it is not assumed that a single pass exceeds 15s
Common error troubleshooting
| Error / Symptom | Cause | Solution |
|---|---|---|
401 Unauthorized |
API Key is invalid or expired | re-execute --setup --api-key <新key> |
422 images 超限 |
the total number of images in omni mode exceeds 9 | reduce the number of --images to ≤9 |
duration 不合法 |
a non-3–15 integer was passed in (such as 2, 16, 5.5) | confirm that --duration is an integer from 3–15 |
| audio / video parameter error | --audios / --videos was passed in with a base64: prefix |
audio and video only accept the url: prefix; only images can use base64 |
| polling timed out (>10 minutes) | platform queue is busy or network abnormality | wait and resubmit; check network connectivity |
| Key file not found | not configured on first use | first execute the Step 2 configuration process |
| generated result differs greatly from the prompt | prompt is too long or information overload | streamline the prompt to the core elements; refer to references/examples.md |