Initial commit: add all skills files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 16:52:49 +08:00
commit 6487becf60
396 changed files with 108871 additions and 0 deletions
--- a/frontend-dev/references/asset-prompt-guide.md
+++ b/frontend-dev/references/asset-prompt-guide.md
@@ -0,0 +1,43 @@
+# Prompt Engineering Guide
+
+## Image Prompts
+
+- Be specific about composition: "left-aligned subject with negative space on the right for text overlay"
+- Specify lighting: "soft studio lighting", "golden hour backlight", "flat diffused light"
+- Include style modifiers: "editorial photography", "3D render", "flat vector illustration"
+- Add technical specs: "4K resolution, sharp focus, shallow depth of field"
+- For web assets: always mention "clean background", "web-optimized", "high contrast for readability"
+- **NEVER** include text in image prompts unless explicitly requested — AI text rendering is unreliable
+
+## Video Prompts
+
+- Use MiniMax camera commands in brackets: `[Push in]`, `[Truck left]`, `[Tracking shot]`, etc.
+- Describe scene, subject, lighting, and mood — the API auto-optimizes prompts by default
+- For web backgrounds: keep 6s duration, add `[Static shot]` for stability
+- Max 2,000 characters
+
+## Audio / TTS
+
+- Specify genre, tempo (BPM), mood, and instruments
+- For background music: "no vocals, suitable for background, not distracting"
+- For sound effects: be extremely specific about the sound event
+- For TTS: choose voice matching content language and speaker gender
+
+## Preset Shortcuts
+
+| Shortcut | Spec |
+|----------|------|
+| `hero` | 16:9 (1280x720) image, cinematic, text-safe space |
+| `thumb` | 1:1 (1024x1024) image, centered subject |
+| `icon` | 1:1 (1024x1024), flat style, clean background |
+| `avatar` | 1:1 (1024x1024), portrait, circular crop ready |
+| `banner` | 21:9 (1344x576), OG/social banner |
+| `portrait` | 2:3 (832x1248), vertical portrait |
+| `mobile` | 9:16 (720x1280), mobile fullscreen |
+| `bg-video` | 768P, 6s, `[Static shot]`, MiniMax Hailuo-2.3 |
+| `video` | 768P, 6s, MiniMax Hailuo-2.3, prompt auto-optimized |
+| `video-hd` | 1080P, 6s, MiniMax Hailuo-2.3 |
+| `bgm` | 30s background music, no vocals, loopable |
+| `sfx` | Short sound effect, < 3s |
+| `tts` | Text-to-speech, MiniMax HD, MP3 |
+| `narration` | Expressive narration voice, MiniMax |
--- a/frontend-dev/references/env-setup.md
+++ b/frontend-dev/references/env-setup.md
@@ -0,0 +1,33 @@
+# Getting Started
+
+## 1. Set API key
+
+```bash
+export MINIMAX_API_KEY="<paste-your-key-here>"
+```
+
+## 2. Install dependencies
+
+```bash
+pip install requests
+
+# FFmpeg (optional, for audio post-processing)
+# macOS:
+brew install ffmpeg
+# Ubuntu:
+sudo apt install ffmpeg
+```
+
+## 3. Quick test
+
+```bash
+python scripts/minimax_tts.py "Hello world" -o test.mp3
+```
+
+If successful, you'll see `OK: xxxxx bytes -> test.mp3`.
+
+## Next steps
+
+- **Voice selection**: See [minimax-voice-catalog.md](minimax-voice-catalog.md)
+- **TTS workflows**: See [minimax-tts-guide.md](minimax-tts-guide.md)
+- **Troubleshooting**: See [troubleshooting.md](troubleshooting.md)
--- a/frontend-dev/references/minimax-cli-reference.md
+++ b/frontend-dev/references/minimax-cli-reference.md
@@ -0,0 +1,133 @@
+# Provider Reference — MiniMax
+
+All asset generation uses MiniMax API. Env: `MINIMAX_API_KEY` (required).
+
+## Audio (Sync TTS)
+
+**Script:** `scripts/minimax_tts.py`
+
+```bash
+python scripts/minimax_tts.py "Hello world" -o output.mp3
+python scripts/minimax_tts.py "你好" -o hi.mp3 -v female-shaonv
+python scripts/minimax_tts.py "Welcome" -o out.wav -v male-qn-jingying --speed 0.8 --format wav
+```
+
+**Model:** `speech-2.8-hd` (default).
+
+| Flag | Default | Range / Options |
+|------|---------|-----------------|
+| `-o` | (required) | Output file path |
+| `-v` | `male-qn-qingse` | Voice ID |
+| `--model` | `speech-2.8-hd` | speech-2.8-hd / speech-2.8-turbo / speech-2.6-hd / speech-2.6-turbo |
+| `--speed` | 1.0 | 0.5–2.0 |
+| `--volume` | 1.0 | 0.1–10 |
+| `--pitch` | 0 | -12 to 12 |
+| `--emotion` | (auto) | happy / sad / angry / fearful / disgusted / surprised / calm / fluent / whisper |
+| `--format` | mp3 | mp3 / wav / flac |
+| `--lang` | auto | Language boost |
+
+**Programmatic:**
+```python
+from minimax_tts import tts
+audio_bytes = tts("Hello", voice_id="female-shaonv")
+```
+
+
+## Video (Text-to-Video)
+
+**Script:** `scripts/minimax_video.py`
+
+```bash
+python scripts/minimax_video.py "A cat playing piano" -o cat.mp4
+python scripts/minimax_video.py "Ocean waves [Truck left]" -o waves.mp4 --duration 10
+python scripts/minimax_video.py "City skyline [Push in]" -o city.mp4 --resolution 1080P
+```
+
+**Model:** `MiniMax-Hailuo-2.3` (default). Async: script handles create → poll → download automatically.
+
+| Flag | Default | Options |
+|------|---------|---------|
+| `-o` | (required) | Output file path (.mp4) |
+| `--model` | `MiniMax-Hailuo-2.3` | MiniMax-Hailuo-2.3 / MiniMax-Hailuo-02 / T2V-01-Director / T2V-01 |
+| `--duration` | 6 | 6 / 10 (10s only at 768P with Hailuo models) |
+| `--resolution` | 768P | 720P / 768P / 1080P (1080P only 6s) |
+| `--no-optimize` | false | Disable prompt auto-optimization |
+| `--poll-interval` | 10 | Seconds between status checks |
+| `--max-wait` | 600 | Max wait time in seconds |
+
+**Camera commands** — insert `[Command]` in prompt: `[Push in]`, `[Truck left]`, `[Pan right]`, `[Zoom out]`, `[Static shot]`, `[Tracking shot]`, etc.
+
+**Programmatic:**
+```python
+from minimax_video import generate
+generate("A cat playing piano", "cat.mp4", model="MiniMax-Hailuo-2.3", duration=6)
+```
+
+See [minimax-video-guide.md](minimax-video-guide.md) for full camera command list and model compatibility.
+
+## Image (Text-to-Image)
+
+**Script:** `scripts/minimax_image.py`
+
+```bash
+python scripts/minimax_image.py "A cat astronaut in space" -o cat.png
+python scripts/minimax_image.py "Mountain landscape" -o hero.png --ratio 16:9
+python scripts/minimax_image.py "Product icons, flat style" -o icons.png -n 4 --seed 42
+```
+
+**Model:** `image-01`. Sync: returns image URL (or base64) immediately.
+
+| Flag | Default | Options |
+|------|---------|---------|
+| `-o` | (required) | Output file path (.png/.jpg) |
+| `--ratio` | 1:1 | 1:1 / 16:9 / 4:3 / 3:2 / 2:3 / 3:4 / 9:16 / 21:9 |
+| `-n` | 1 | Number of images (1–9) |
+| `--seed` | (random) | Seed for reproducibility |
+| `--optimize` | false | Enable prompt auto-optimization |
+| `--base64` | false | Return base64 instead of URL |
+
+**Batch output:** with `-n > 1`, files are named `out-0.png`, `out-1.png`, etc.
+
+**Programmatic:**
+```python
+from minimax_image import generate_image, download_and_save
+result = generate_image("A cat in space", aspect_ratio="16:9")
+download_and_save(result["data"]["image_urls"][0], "cat.png")
+```
+
+See [minimax-image-guide.md](minimax-image-guide.md) for ratio dimensions and details.
+
+## Music (Text-to-Music)
+
+**Script:** `scripts/minimax_music.py`
+
+```bash
+python scripts/minimax_music.py --prompt "Indie folk, melancholic" --lyrics "[verse]\nStreetlights flicker" -o song.mp3
+python scripts/minimax_music.py --prompt "Upbeat pop, energetic" --auto-lyrics -o pop.mp3
+python scripts/minimax_music.py --prompt "Jazz piano, smooth, relaxing" --instrumental -o jazz.mp3
+```
+
+**Model:** `music-2.5+` (default). Sync: returns audio hex or URL.
+
+| Flag | Default | Options |
+|------|---------|---------|
+| `-o` | (required) | Output file path (.mp3/.wav) |
+| `--prompt` | (empty) | Music description: style, mood, scenario (max 2000 chars) |
+| `--lyrics` | (empty) | Song lyrics with structure tags (max 3500 chars) |
+| `--lyrics-file` | (empty) | Read lyrics from file |
+| `--model` | `music-2.5+` | music-2.5+ / music-2.5 |
+| `--instrumental` | false | Generate instrumental only (no vocals, music-2.5+ only) |
+| `--auto-lyrics` | false | Auto-generate lyrics from prompt |
+| `--format` | mp3 | mp3 / wav / pcm |
+| `--sample-rate` | 44100 | 16000 / 24000 / 32000 / 44100 |
+| `--bitrate` | 256000 | 32000 / 64000 / 128000 / 256000 |
+
+**Lyrics structure tags:** `[Intro]`, `[Verse]`, `[Pre Chorus]`, `[Chorus]`, `[Interlude]`, `[Bridge]`, `[Outro]`, `[Post Chorus]`, `[Transition]`, `[Break]`, `[Hook]`, `[Build Up]`, `[Inst]`, `[Solo]`
+
+**Programmatic:**
+```python
+from minimax_music import generate_music
+result = generate_music(prompt="Jazz piano", is_instrumental=True)
+with open("jazz.mp3", "wb") as f:
+    f.write(result["audio_bytes"])
+```
--- a/frontend-dev/references/minimax-image-guide.md
+++ b/frontend-dev/references/minimax-image-guide.md
@@ -0,0 +1,65 @@
+# Image Generation Guide
+
+## CLI usage
+
+```bash
+# Basic (1:1, 1024x1024)
+python scripts/minimax_image.py "A cat astronaut floating in space" -o cat.png
+
+# 16:9 for hero banner
+python scripts/minimax_image.py "Mountain landscape at golden hour" -o hero.png --ratio 16:9
+
+# Batch: 4 images at once
+python scripts/minimax_image.py "Minimalist product icon" -o icons.png -n 4
+
+# With seed for reproducibility
+python scripts/minimax_image.py "Abstract gradient background" -o bg.png --seed 42
+
+# Enable prompt optimization
+python scripts/minimax_image.py "a dog" -o dog.png --optimize
+
+# Base64 mode (no URL download, save directly)
+python scripts/minimax_image.py "Logo concept" -o logo.png --base64
+```
+
+## Programmatic usage
+
+```python
+from minimax_image import generate_image, download_and_save
+
+# Generate and get URL
+result = generate_image("A cat in space", aspect_ratio="16:9")
+url = result["data"]["image_urls"][0]
+download_and_save(url, "cat.png")
+
+# Generate multiple
+result = generate_image("Icon design", n=4, aspect_ratio="1:1")
+for i, url in enumerate(result["data"]["image_urls"]):
+    download_and_save(url, f"icon-{i}.png")
+```
+
+## Model
+
+Currently only `image-01`.
+
+## Aspect ratios & dimensions
+
+| Ratio | Pixels | Use case |
+|-------|--------|----------|
+| `1:1` | 1024x1024 | Avatar, icon, square thumbnail |
+| `16:9` | 1280x720 | Hero banner, video thumbnail |
+| `4:3` | 1152x864 | Standard landscape |
+| `3:2` | 1248x832 | Photo-style |
+| `2:3` | 832x1248 | Portrait, mobile |
+| `3:4` | 864x1152 | Portrait card |
+| `9:16` | 720x1280 | Mobile fullscreen, story |
+| `21:9` | 1344x576 | Ultra-wide banner |
+
+Custom dimensions also supported: width/height in [512, 2048], must be divisible by 8.
+
+## Limits
+
+- Prompt: max 1,500 characters
+- Batch: 1–9 images per request
+- URL expires after 24 hours (use `--base64` to avoid expiry)
+- Seed: set for reproducible results across identical prompts
--- a/frontend-dev/references/minimax-music-guide.md
+++ b/frontend-dev/references/minimax-music-guide.md
@@ -0,0 +1,216 @@
+# Music Generation Guide
+
+## CLI Usage
+
+```bash
+# Instrumental (no vocals)
+python scripts/minimax_music.py --prompt "Jazz piano, smooth, relaxing" --instrumental -o jazz.mp3
+
+# With custom lyrics
+python scripts/minimax_music.py --prompt "Indie folk, melancholic" --lyrics "[verse]\nStreetlights flicker\nOn empty roads" -o song.mp3
+
+# Auto-generate lyrics from prompt
+python scripts/minimax_music.py --prompt "Upbeat pop, energetic, summer vibes" --auto-lyrics -o pop.mp3
+
+# From lyrics file
+python scripts/minimax_music.py --prompt "Soulful blues, rainy night" --lyrics-file lyrics.txt -o blues.mp3
+
+# Custom audio settings
+python scripts/minimax_music.py --prompt "Lo-fi beats" --instrumental -o lofi.wav --format wav --sample-rate 44100 --bitrate 256000
+```
+
+## Programmatic Usage
+
+```python
+from minimax_music import generate_music
+
+# Instrumental
+result = generate_music(prompt="Jazz piano, smooth", is_instrumental=True)
+with open("jazz.mp3", "wb") as f:
+    f.write(result["audio_bytes"])
+
+# With lyrics
+result = generate_music(
+    prompt="Indie folk, acoustic guitar",
+    lyrics="[verse]\nWalking through the rain\n[chorus]\nI'll find my way home",
+)
+
+# Auto-generate lyrics
+result = generate_music(
+    prompt="Upbeat pop, summer anthem",
+    lyrics_optimizer=True,
+)
+
+# Access metadata
+print(f"Duration: {result['duration']}ms")
+print(f"Sample rate: {result['sample_rate']}")
+print(f"Size: {result['size']} bytes")
+```
+
+## Models
+
+| Model | Features |
+|-------|----------|
+| `music-2.5+` | Recommended. Supports instrumental mode, complete song structures, hi-fi audio |
+| `music-2.5` | Standard model. No instrumental mode |
+
+## Prompt Writing
+
+The `prompt` parameter describes music style using comma-separated descriptors:
+
+| Category | Examples |
+|----------|----------|
+| Genre | Blues, Pop, Rock, Jazz, Electronic, Hip-hop, Folk, Classical |
+| Mood | Soulful, Melancholy, Upbeat, Energetic, Peaceful, Dark, Nostalgic |
+| Scenario | Rainy night, Summer day, Road trip, Late night, Sunrise |
+| Instrumentation | Electric guitar, Piano, Acoustic, Synthesizer, Strings |
+| Vocal type | Male vocals, Female vocals, Soft vocals, Powerful vocals |
+| Tempo | Slow tempo, Fast tempo, Mid-tempo, Relaxed |
+
+**Example prompts:**
+```
+"Soulful Blues, Rainy Night, Melancholy, Male Vocals, Slow Tempo"
+"Upbeat Pop, Summer Vibes, Female Vocals, Energetic, Synth-heavy"
+"Lo-fi Hip-hop, Chill, Relaxed, Instrumental, Piano samples"
+"Cinematic Orchestral, Epic, Building tension, Strings and Brass"
+```
+
+## Lyrics Format
+
+Use structure tags in brackets to organize song sections:
+
+### Structure Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `[Intro]` | Opening section (can be instrumental) |
+| `[Verse]` / `[Verse 1]` | Story/narrative sections |
+| `[Pre-Chorus]` | Build-up before chorus |
+| `[Chorus]` | Main hook, typically repeated |
+| `[Post Chorus]` | Extension after chorus |
+| `[Bridge]` | Contrasting section near end |
+| `[Interlude]` | Instrumental break |
+| `[Solo]` | Instrumental solo (add direction: "slow, bluesy") |
+| `[Outro]` | Closing section |
+| `[Break]` | Short pause or transition |
+| `[Hook]` | Catchy repeated phrase |
+| `[Build Up]` | Tension building section |
+| `[Inst]` | Instrumental section |
+| `[Transition]` | Section change |
+
+### Backing Vocals & Directions
+
+Use parentheses for backing vocals or performance notes:
+```
+(Ooh, yeah)
+(Harmonize)
+(Whispered)
+(Fade out...)
+```
+
+### Example Lyrics
+
+```
+[Intro]
+(Soft piano)
+
+[Verse 1]
+Streetlights flicker on empty roads
+The rain keeps falling, the wind still blows
+I'm walking home with nowhere to go
+Just memories of what I used to know
+
+[Pre-Chorus]
+And I can feel it coming back to me
+(Coming back to me)
+
+[Chorus]
+Under the neon lights tonight
+I'm searching for what feels right
+(Oh, feels right)
+These city streets will guide me home
+I'm tired of feeling so alone
+
+[Verse 2]
+Coffee shops and midnight trains
+The faces change but the feeling remains
+...
+
+[Bridge]
+Maybe tomorrow will be different
+Maybe I'll finally understand
+(Understand...)
+
+[Solo]
+(Slow, mournful, bluesy guitar)
+
+[Outro]
+(Fade out...)
+Under the neon lights...
+```
+
+## Audio Settings
+
+| Parameter | Options | Default | Notes |
+|-----------|---------|---------|-------|
+| `format` | mp3, wav, pcm | mp3 | WAV for highest quality |
+| `sample_rate` | 16000, 24000, 32000, 44100 | 44100 | 44100 recommended |
+| `bitrate` | 32000, 64000, 128000, 256000 | 256000 | Higher = better quality |
+
+## Generation Modes
+
+### 1. Instrumental Only
+```bash
+python scripts/minimax_music.py --prompt "Ambient electronic, space theme" --instrumental -o ambient.mp3
+```
+- Requires `music-2.5+` model
+- Only `prompt` needed, no lyrics
+
+### 2. With Custom Lyrics
+```bash
+python scripts/minimax_music.py --prompt "Pop ballad, emotional" --lyrics "[verse]\nYour lyrics here" -o ballad.mp3
+```
+- Provide both `prompt` (style) and `lyrics` (words + structure)
+
+### 3. Auto-Generated Lyrics
+```bash
+python scripts/minimax_music.py --prompt "Rock anthem about freedom" --auto-lyrics -o rock.mp3
+```
+- System generates lyrics from prompt
+- Good for quick generation when lyrics aren't critical
+
+## Limits
+
+- **Prompt:** max 2,000 characters
+- **Lyrics:** 1–3,500 characters
+- **Duration:** ~25-30 seconds per generation (varies)
+- **URL expiration:** 24 hours (when using URL output mode)
+
+## Best Practices
+
+1. **Layer style descriptors** — Combine genre + mood + instrumentation for precise results
+2. **Use structure tags** — Even simple `[verse]` `[chorus]` improves arrangement
+3. **Include backing vocal cues** — `(Ooh)`, `(Yeah)` add production polish
+4. **Match prompt to lyrics mood** — Conflicting prompt/lyrics produce inconsistent results
+5. **Instrumental for backgrounds** — Use `--instrumental` for BGM, avoiding vocal distractions
+6. **High bitrate for production** — Use 256000 for final assets, lower for drafts
+
+## Common Use Cases
+
+| Use Case | Command |
+|----------|---------|
+| Background music | `--prompt "Lo-fi, calm, ambient" --instrumental` |
+| Landing page hero | `--prompt "Cinematic, inspiring, building" --instrumental` |
+| Podcast intro | `--prompt "Upbeat, energetic, short" --instrumental` |
+| Demo song | `--prompt "Pop, catchy" --auto-lyrics` |
+| Custom jingle | `--prompt "Happy, bright, corporate" --lyrics "[hook]\nYour brand name"` |
+
+## Error Handling
+
+| Error Code | Meaning | Solution |
+|------------|---------|----------|
+| 1002 | Rate limit | Wait and retry |
+| 1004 | Auth failed | Check API key |
+| 1008 | Insufficient balance | Top up account |
+| 1026 | Content flagged | Rephrase prompt/lyrics |
+| 2013 | Invalid parameters | Check prompt/lyrics length |
--- a/frontend-dev/references/minimax-tts-guide.md
+++ b/frontend-dev/references/minimax-tts-guide.md
@@ -0,0 +1,78 @@
+# TTS Guide
+
+## CLI usage (recommended)
+
+```bash
+# Basic
+python scripts/minimax_tts.py "Hello world" -o output.mp3
+
+# Custom voice and speed
+python scripts/minimax_tts.py "你好世界" -o hi.mp3 -v female-shaonv --speed 0.9
+
+# WAV format, high quality
+python scripts/minimax_tts.py "Welcome" -o out.wav -v male-qn-jingying --format wav --sample-rate 32000
+
+# With emotion (for speech-2.6 models)
+python scripts/minimax_tts.py "Great news!" -o happy.mp3 -v female-shaonv --emotion happy --model speech-2.6-hd
+```
+
+## Programmatic usage
+
+```python
+from minimax_tts import tts
+
+# Basic
+audio_bytes = tts("Hello world")
+
+# With options
+audio_bytes = tts(
+    text="Welcome to our product.",
+    voice_id="female-shaonv",
+    model="speech-2.8-hd",
+    speed=0.9,
+    fmt="mp3",
+)
+
+# Save to file
+with open("output.mp3", "wb") as f:
+    f.write(audio_bytes)
+```
+
+## Limits
+
+- **Sync TTS:** max 10,000 characters per request
+- **Pause markers:** insert `<#1.5#>` for a 1.5s pause (range: 0.01–99.99s)
+
+## Model selection
+
+| Model | Best for |
+|-------|----------|
+| `speech-2.8-hd` | Highest quality, auto emotion (recommended) |
+| `speech-2.8-turbo` | Fast, good quality |
+| `speech-2.6-hd` | Manual emotion control needed |
+| `speech-2.6-turbo` | Fast + manual emotion |
+
+## Voice selection
+
+See [minimax-voice-catalog.md](minimax-voice-catalog.md) for the full list.
+
+Common voices:
+
+| Voice ID | Gender | Style |
+|----------|--------|-------|
+| `male-qn-qingse` | Male | Young, gentle |
+| `male-qn-jingying` | Male | Elite, authoritative |
+| `male-qn-badao` | Male | Dominant, powerful |
+| `female-shaonv` | Female | Young, bright |
+| `female-yujie` | Female | Mature, elegant |
+| `female-chengshu` | Female | Sophisticated |
+| `presenter_male` | Male | News presenter |
+| `presenter_female` | Female | News presenter |
+| `audiobook_male_1` | Male | Audiobook narrator |
+| `audiobook_female_1` | Female | Audiobook narrator |
+
+## Best practices
+
+- Use `speech-2.8-hd` and let emotion auto-match — don't manually set emotion unless needed
+- Use 32000 sample rate for web audio (good balance of quality and file size)
+- For long text (>10,000 chars), split into chunks and merge with FFmpeg
--- a/frontend-dev/references/minimax-video-guide.md
+++ b/frontend-dev/references/minimax-video-guide.md
@@ -0,0 +1,82 @@
+# Video Generation Guide
+
+## CLI usage
+
+```bash
+# Basic
+python scripts/minimax_video.py "A cat playing piano in a cozy room" -o cat.mp4
+
+# With camera control
+python scripts/minimax_video.py "Ocean waves crashing on rocks [Truck left]" -o waves.mp4
+
+# 10 seconds, 1080P
+python scripts/minimax_video.py "City skyline at sunset [Push in]" -o city.mp4 --duration 10 --resolution 1080P
+
+# Disable prompt auto-optimization
+python scripts/minimax_video.py "Exact prompt I want used" -o out.mp4 --no-optimize
+```
+
+## Programmatic usage
+
+```python
+from minimax_video import generate, create_task, poll_task, download_video
+
+# Full pipeline (blocking)
+generate("A cat playing piano", "cat.mp4", model="MiniMax-Hailuo-2.3", duration=6)
+
+# Step by step
+task_id = create_task("A cat playing piano")
+file_id = poll_task(task_id, interval=10, max_wait=600)
+download_video(file_id, "cat.mp4")
+```
+
+## Models
+
+| Model | Resolution | Duration | Notes |
+|-------|-----------|----------|-------|
+| `MiniMax-Hailuo-2.3` | 768P, 1080P | 6s, 10s (768P only) | Latest, recommended |
+| `MiniMax-Hailuo-02` | 768P, 1080P | 6s, 10s (768P only) | Previous gen |
+| `T2V-01-Director` | 720P | 6s | Camera control optimized |
+| `T2V-01` | 720P | 6s | Base model |
+
+## Camera commands
+
+Insert `[Command]` in prompt text to control camera movement:
+
+| Command | Effect |
+|---------|--------|
+| `[Truck left]` | Camera moves left |
+| `[Truck right]` | Camera moves right |
+| `[Push in]` | Camera moves toward subject |
+| `[Pull out]` | Camera moves away from subject |
+| `[Pan left]` | Camera rotates left (fixed position) |
+| `[Pan right]` | Camera rotates right (fixed position) |
+| `[Tilt up]` | Camera tilts upward |
+| `[Tilt down]` | Camera tilts downward |
+| `[Pedestal up]` | Camera rises vertically |
+| `[Pedestal down]` | Camera lowers vertically |
+| `[Zoom in]` | Lens zooms in |
+| `[Zoom out]` | Lens zooms out |
+| `[Static shot]` | No camera movement |
+| `[Tracking shot]` | Camera follows subject |
+| `[Shake]` | Handheld shake effect |
+
+Example: `"A runner sprints through a forest trail [Tracking shot]"`
+
+## Pipeline
+
+The script handles the full async flow:
+
+1. **Create task** — `POST /v1/video_generation` → returns `task_id`
+2. **Poll status** — `GET /v1/query/video_generation?task_id=xxx` → poll until `Success`
+   - Status values: `Preparing` → `Queueing` → `Processing` → `Success` / `Fail`
+3. **Download** — `GET /v1/files/retrieve?file_id=xxx` → get `download_url` (valid 1 hour) → save file
+
+Typical generation time: 1–5 minutes depending on duration and resolution.
+
+## Limits
+
+- Prompt: max 2,000 characters
+- 1080P: only supports 6s duration
+- 10s duration: only available at 768P with Hailuo-2.3/02
+- Download URL expires after 1 hour
--- a/frontend-dev/references/minimax-voice-catalog.md
+++ b/frontend-dev/references/minimax-voice-catalog.md
@@ -0,0 +1,686 @@
+# MiniMax Voice Catalog
+
+Complete reference for all available voices in the MiniMax Voice API.
+
+## Contents
+
+- [Voice Recommendation](#voice-recommendation) - Find voices by content type and characteristics
+- [System Voices List (categorized by language)](#system-voices-list-categorized-by-language) - Complete voice database by language
+- [Voice Parameters](#voice-parameters) - Configure voice settings (speed, volume, pitch, emotion)
+- [Custom Voices](#custom-voices) - Voice cloning and voice design options
+- [Voice Comparison Table](#voice-comparison-table) - Quick reference comparison
+- [Voice IDs for Quick Reference](#voice-ids-for-quick-reference) - Most popular voices at a glance
+
+---
+
+## 1. How to Choose a Voice
+
+When selecting a voice, follow this two-step decision process to ensure the voice matches the scenario, gender, age, and language of the character.
+
+### Step 1: Identify the Usage Scenario
+
+First, determine whether your content falls into one of the **three professional domains** listed in **Section 2.1**:
+
+| Professional Domain | Examples |
+|---|---|
+| **Narration & Narrator in Storytelling** | suitable for the narrator in Audiobooks, fiction narration, storytelling |
+| **News & Announcements** | suitable for news broadcasts, formal announcements, press releases |
+| **Documentary** | suitable for documentary narration, commentary, educational films |
+
+**If your content matches one of these professional domains:**
+→ Prioritize selecting from the recommended voices in **Section 2.1**, filtering by scenario and the speaker's **gender**.
+These voices are specifically optimized for their respective professional use cases (pacing, clarity, tone).
+
+**If your content does NOT fall into these three professional domains:**
+→ Proceed to Step 2 below.
+
+### Step 2: Select by Character Traits (Gender + Age + Language)
+
+For non-professional scenarios, select a voice from **Section 2.2** based on the following three character traits, in strict priority order:
+
+1. **Gender** (highest priority, non-negotiable)
+   - Male characters → **must** use male voices
+   - Female characters → **must** use female voices
+   - Never mismatch gender, even if other traits seem to fit
+
+2. **Age** (determines which subsection to look in)
+   - **Children** → Section 2.2 "Children's Voices"
+   - **Youth** (teens, young adults) → Section 2.2 "Youthful Voices"
+   - **Adult** → Section 2.2 "Adult Voices"
+   - **Elderly** → Section 2.2 "Elderly Voices"
+
+3. **Language** (must match the content language)
+   - The voice **must** match the language of the content being generated
+   - Chinese content → select Chinese voices; Korean content → select Korean voices; English content → select English voices, etc.
+   - If no exact language match exists in Section 2.2, fall back to the full **System Voices List** (Section 3) for the target language
+
+After narrowing down candidates by these three traits, choose the best match based on the voice's **personality**, **tone**, and **use case** as described in each voice entry.
+
+### Quick Reference Decision Flow
+
+```
+Content Type?
+├── Story/Narration/News/Documentary → Section 2.1 (filter by scenario + gender)
+└── Other scenarios → Section 2.2:
+    ├── 1. Match Gender (mandatory)
+    ├── 2. Match Age Group (Children/Youth/Adult/Elderly/Professional)
+    ├── 3. Match Language (must match content language)
+    └── 4. Choose best fit by personality/tone
+```
+
+---
+
+
+## 2. Voice Recommendation
+
+### 2.1 By Content Type
+
+**Narration & Narrator in Storytelling**
+- Recommended: `audiobook_female_1`, `audiobook_male_1`
+- Characteristics: suitable for narrating stories, sustained performance, clear articulation, good pacing
+
+**News & Announcements**
+- Recommended: `Chinese (Mandarin)_News_Anchor`, `Chinese (Mandarin)_Male_Announcer`
+- Characteristics: Authoritative, clear, professional pacing
+
+**Documentary**
+- Recommended: `doc_commentary`
+- Characteristics: Professional, clear, consistent pacing
+
+
+### 2.2 By Characteristics
+
+#### Children's Voices
+
+| voice_id | Name | Description | Best For | Language |
+|----------|------|-------------|----------|----------|
+| `clever_boy` | 聪明男童 | Smart, witty boy voice | Children's content, educational | Chinese (Mandarin) |
+| `cute_boy` | 可爱男童 | Adorable young boy voice | Kids' content, animations | Chinese (Mandarin) |
+| `lovely_girl` | 萌萌女童 | Cute, sweet girl voice | Children's stories, games | Chinese (Mandarin) |
+| `cartoon_pig` | 卡通猪小琪 | Cartoon character voice | Animations, comedy, entertainment | Chinese (Mandarin) |
+| `Korean_SweetGirl` | Sweet Girl | Sweet, adorable young girl voice | Children's content, romance | Korean |
+| `Indonesian_SweetGirl` | Sweet Girl | Sweet, adorable girl voice | Children's content, friendly | Indonesian |
+| `English_Sweet_Girl` | Sweet Girl | Sweet, innocent young girl voice | Children's content, friendly | English |
+| `Spanish_Kind-heartedGirl` | Kind-hearted Girl | Warm, compassionate girl voice | Children's content, warm | Spanish |
+| `Portuguese_Kind-heartedGirl` | Kind-hearted Girl | Warm, compassionate girl voice | Children's content, warm | Portuguese |
+
+#### Youthful Voices
+
+| voice_id | Name | Description | Best For | Language |
+|----------|------|-------------|----------|----------|
+| `male-qn-qingse` | 青涩青年 | Youthful, inexperienced young man voice | Campus stories, coming-of-age content | Chinese (Mandarin) |
+| `male-qn-daxuesheng` | 青年大学生 | Young university student voice | Campus content, educational | Chinese (Mandarin) |
+| `female-shaonv` | 少女 | Young maiden voice | Romance, youth content | Chinese (Mandarin) |
+| `bingjiao_didi` | 病娇弟弟 | Tsundere young brother voice | Romance, character-driven content | Chinese (Mandarin) |
+| `junlang_nanyou` | 俊朗男友 | Handsome boyfriend voice | Romance, dating content | Chinese (Mandarin) |
+| `chunzhen_xuedi` | 纯真学弟 | Innocent junior student voice | Campus stories, youth content | Chinese (Mandarin) |
+| `lengdan_xiongzhang` | 冷淡学长 | Cool senior student voice | Campus stories, romance | Chinese (Mandarin) |
+| `diadia_xuemei` | 嗲嗲学妹 | Flirty junior girl voice | Romance, dating content | Chinese (Mandarin) |
+| `danya_xuejie` | 淡雅学姐 | Elegant senior girl voice | Campus stories, romance | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Straightforward_Boy` | 率真弟弟 | Frank, straightforward boy voice | Casual, direct content | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Sincere_Adult` | 真诚青年 | Sincere young adult voice | Honest, genuine content | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Pure-hearted_Boy` | 清澈邻家弟弟 | Pure-hearted neighbor boy voice | Innocent, wholesome content | Chinese (Mandarin) |
+| `Korean_CheerfulBoyfriend` | Cheerful Boyfriend | Energetic, loving boyfriend voice | Romance, dating content | Korean |
+| `Korean_ShyGirl` | Shy Girl | Timid, reserved girl voice | Comedy, romance | Korean |
+| `Japanese_SportyStudent` | Sporty Student | Energetic athletic student voice | Sports, youth content | Japanese |
+| `Japanese_InnocentBoy` | Innocent Boy | Pure, naive young boy voice | Children's content | Japanese |
+| `Spanish_SincereTeen` | SincereTeen | Honest, genuine teenager voice | Youth, authentic | Spanish |
+| `Spanish_Strong-WilledBoy` | Strong-willed Boy | Determined, persistent boy voice | Youth, motivation | Spanish |
+
+#### Adult Voices
+
+| voice_id | Name | Description | Best For | Language |
+|----------|------|-------------|----------|----------|
+| `female-chengshu` | 成熟女性 | Mature woman voice | Sophisticated, adult content | Chinese (Mandarin) |
+| `female-yujie` | 御姐 | Mature, elegant woman voice | Romance, professional content | Chinese (Mandarin) |
+| `female-tianmei` | 甜美女性 | Sweet, pleasant woman voice | Soft, gentle content | Chinese (Mandarin) |
+| `badao_shaoye` | 霸道少爷 | Arrogant young master voice | Drama, character roles | Chinese (Mandarin) |
+| `wumei_yujie` | 妩媚御姐 | Charming mature woman voice | Romance, mature content | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Gentleman` | 温润男声 | Gentle, refined male voice | Narration, storytelling | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Unrestrained_Young_Man` | 不羁青年 | Unrestrained young man voice | Casual, entertainment content | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Southern_Young_Man` | 南方小哥 | Southern young man voice | Regional character, casual content | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Gentle_Youth` | 温润青年 | Gentle young man voice | Narration, calm content | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Warm_Girl` | 温暖少女 | Warm young girl voice | Friendly, supportive content | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Soft_Girl` | 柔和少女 | Soft, gentle girl voice | Calm, soothing content | Chinese (Mandarin) |
+| `Korean_PlayboyCharmer` | Playboy Charmer | Smooth, flirtatious male voice | Romance, entertainment | Korean |
+| `Korean_CalmLady` | Calm Lady | Composed, serene female voice | Meditation, relaxation | Korean |
+| `Spanish_ConfidentWoman` | Confident Woman | Self-assured, capable woman voice | Professional, empowerment | Spanish |
+| `Portuguese_ConfidentWoman` | Confident Woman | Self-assured, capable woman voice | Professional, empowerment | Portuguese |
+
+#### Elderly Voices
+
+| voice_id | Name | Description | Best For | Language |
+|----------|------|-------------|----------|----------|
+| `Chinese (Mandarin)_Humorous_Elder` | 搞笑大爷 | Humorous old man voice | Comedy, entertainment | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Kind-hearted_Elder` | 花甲奶奶 | Kind elderly lady voice | Stories, warm content | Chinese (Mandarin) |
+| `Chinese (Mandarin)_Kind-hearted_Antie` | 热心大婶 | Kind-hearted auntie voice | Warm, friendly content | Chinese (Mandarin) |
+| `Japanese_IntellectualSenior` | Intellectual Senior | Wise, knowledgeable elder voice | Narration, educational | Japanese |
+| `Korean_IntellectualSenior` | Intellectual Senior | Wise, knowledgeable elder voice | Educational, narration | Korean |
+| `Spanish_Wiselady` | Wise Lady | Experienced, wise woman voice | Guidance, advice | Spanish |
+| `Portuguese_Wiselady` | Wise Lady | Experienced, wise woman voice | Guidance, advice | Portuguese |
+| `Spanish_SereneElder` | Serene Elder | Calm, peaceful elderly voice | Meditation, wisdom | Spanish |
+| `Portuguese_SereneElder` | Serene Elder | Calm, peaceful elderly voice | Meditation, wisdom | Portuguese |
+| `English_Gentle-voiced_man` | Gentle-voiced Man | Soft-spoken, kind male voice | Calm, supportive content | English |
+
+---
+
+## System Voices List (categorized by language)
+
+### Chinese Mandarin Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `male-qn-qingse` | 青涩青年 | Youthful, inexperienced young man voice | Campus stories, coming-of-age content |
+| `male-qn-badao` | 霸道青年 | Arrogant, dominant young man voice | Drama, romance, character roles |
+| `male-qn-daxuesheng` | 青年大学生 | Young university student voice | Campus content, educational |
+| `female-shaonv` | 少女 | Young maiden voice | Romance, youth content |
+| `female-yujie` | 御姐 | Mature, elegant woman voice | Romance, professional content |
+| `female-chengshu` | 成熟女性 | Mature woman voice | Sophisticated, adult content |
+| `female-tianmei` | 甜美女性 | Sweet, pleasant woman voice | Soft, gentle content |
+| `clever_boy` | 聪明男童 | Smart, witty boy voice | Children's content, educational |
+| `cute_boy` | 可爱男童 | Adorable young boy voice | Kids' content, animations |
+| `lovely_girl` | 萌萌女童 | Cute, sweet girl voice | Children's stories, games |
+| `cartoon_pig` | 卡通猪小琪 | Cartoon character voice | Animations, comedy, entertainment |
+| `bingjiao_didi` | 病娇弟弟 | Tsundere young brother voice | Romance, character-driven content |
+| `junlang_nanyou` | 俊朗男友 | Handsome boyfriend voice | Romance, dating content |
+| `chunzhen_xuedi` | 纯真学弟 | Innocent junior student voice | Campus stories, youth content |
+| `lengdan_xiongzhang` | 冷淡学长 | Cool senior student voice | Campus stories, romance |
+| `badao_shaoye` | 霸道少爷 | Arrogant young master voice | Drama, character roles |
+| `tianxin_xiaoling` | 甜心小玲 | Sweet Xiao Ling voice | Character roles, animations |
+| `qiaopi_mengmei` | 俏皮萌妹 | Playful cute girl voice | Comedy, light-hearted content |
+| `wumei_yujie` | 妩媚御姐 | Charming mature woman voice | Romance, mature content |
+| `diadia_xuemei` | 嗲嗲学妹 | Flirty junior girl voice | Romance, dating content |
+| `danya_xuejie` | 淡雅学姐 | Elegant senior girl voice | Campus stories, romance |
+| `Arrogant_Miss` | 嚣张小姐 | Arrogant young lady voice | Drama, character roles |
+| `Robot_Armor` | 机械战甲 | Robotic armor voice | Sci-fi, game characters |
+| `Chinese (Mandarin)_Reliable_Executive` | 沉稳高管 | Reliable executive voice | Corporate, business content |
+| `Chinese (Mandarin)_News_Anchor` | 新闻女声 | News anchor female voice | News broadcasts, current affairs |
+| `Chinese (Mandarin)_Mature_Woman` | 傲娇御姐 | Tsundere mature woman voice | Romance, character-driven content |
+| `Chinese (Mandarin)_Unrestrained_Young_Man` | 不羁青年 | Unrestrained young man voice | Casual, entertainment content |
+| `male-qn-jingying` | 精英青年 | Elite, ambitious young man voice | Business, professional content |
+| `Chinese (Mandarin)_Kind-hearted_Antie` | 热心大婶 | Kind-hearted auntie voice | Warm, friendly content |
+| `Chinese (Mandarin)_HK_Flight_Attendant` | 港普空姐 | HK accent flight attendant voice | Regional character, entertainment |
+| `Chinese (Mandarin)_Humorous_Elder` | 搞笑大爷 | Humorous old man voice | Comedy, entertainment |
+| `Chinese (Mandarin)_Gentleman` | 温润男声 | Gentle, refined male voice | Narration, storytelling |
+| `Chinese (Mandarin)_Warm_Bestie` | 温暖闺蜜 | Warm bestie female voice | Friendly, supportive content |
+| `Chinese (Mandarin)_Male_Announcer` | 播报男声 | Male announcer voice | Announcements, broadcasts |
+| `Chinese (Mandarin)_Sweet_Lady` | 甜美女声 | Sweet lady voice | Soft, gentle content |
+| `Chinese (Mandarin)_Southern_Young_Man` | 南方小哥 | Southern young man voice | Regional character, casual content |
+| `Chinese (Mandarin)_Wise_Women` | 阅历姐姐 | Experienced wise woman voice | Advice, guidance content |
+| `Chinese (Mandarin)_Gentle_Youth` | 温润青年 | Gentle young man voice | Narration, calm content |
+| `Chinese (Mandarin)_Warm_Girl` | 温暖少女 | Warm young girl voice | Friendly, supportive content |
+| `Chinese (Mandarin)_Kind-hearted_Elder` | 花甲奶奶 | Kind elderly lady voice | Stories, warm content |
+| `Chinese (Mandarin)_Cute_Spirit` | 憨憨萌兽 | Cute cartoon spirit voice | Animations, children's content |
+| `Chinese (Mandarin)_Radio_Host` | 电台男主播 | Radio host male voice | Podcasts, radio shows |
+| `Chinese (Mandarin)_Lyrical_Voice` | 抒情男声 | Lyrical male singing voice | Music, singing content |
+| `Chinese (Mandarin)_Straightforward_Boy` | 率真弟弟 | Frank, straightforward boy voice | Casual, direct content |
+| `Chinese (Mandarin)_Sincere_Adult` | 真诚青年 | Sincere young adult voice | Honest, genuine content |
+| `Chinese (Mandarin)_Gentle_Senior` | 温柔学姐 | Gentle senior girl voice | Campus stories, supportive content |
+| `Chinese (Mandarin)_Stubborn_Friend` | 嘴硬竹马 | Stubborn childhood friend voice | Drama, character-driven content |
+| `Chinese (Mandarin)_Crisp_Girl` | 清脆少女 | Crisp, clear young girl voice | Clear, bright content |
+| `Chinese (Mandarin)_Pure-hearted_Boy` | 清澈邻家弟弟 | Pure-hearted neighbor boy voice | Innocent, wholesome content |
+| `Chinese (Mandarin)_Soft_Girl` | 柔和少女 | Soft, gentle girl voice | Calm, soothing content |
+
+### Chinese Cantonese Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Cantonese_ProfessionalHost（F)` | 专业女主持 | Professional female host voice | Cantonese broadcasts, hosting |
+| `Cantonese_GentleLady` | 温柔女声 | Gentle Cantonese female voice | Soft, warm Cantonese content |
+| `Cantonese_ProfessionalHost（M)` | 专业男主持 | Professional male host voice | Cantonese broadcasts, hosting |
+| `Cantonese_PlayfulMan` | 活泼男声 | Playful Cantonese male voice | Entertainment, casual content |
+| `Cantonese_CuteGirl` | 可爱女孩 | Cute Cantonese girl voice | Children's content, animations |
+| `Cantonese_KindWoman` | 善良女声 | Kind Cantonese female voice | Warm, friendly content |
+
+### English Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Santa_Claus` | Santa Claus | Festive, jolly male voice | Holiday content, children's stories |
+| `Grinch` | Grinch | Whiny, mischievous voice | Comedy, entertainment, holiday |
+| `Rudolph` | Rudolph | Cute, nasal reindeer voice | Children's content, holiday |
+| `Arnold` | Arnold | Deep, robotic terminator voice | Sci-fi, action, character roles |
+| `Charming_Santa` | Charming Santa | Smooth, charismatic Santa voice | Holiday, entertainment |
+| `Charming_Lady` | Charming Lady | Elegant, sophisticated female voice | Professional, romance |
+| `Sweet_Girl` | Sweet Girl | Sweet, innocent young girl voice | Children's content, friendly |
+| `Cute_Elf` | Cute Elf | Playful, tiny elf voice | Fantasy, children's content |
+| `Attractive_Girl` | Attractive Girl | Attractive, engaging female voice | Entertainment, marketing |
+| `Serene_Woman` | Serene Woman | Calm, peaceful female voice | Meditation, relaxation |
+| `English_Trustworthy_Man` | Trustworthy Man | Reliable, sincere male voice | Business, narration |
+| `English_Graceful_Lady` | Graceful Lady | Elegant, refined female voice | Formal, professional |
+| `English_Aussie_Bloke` | Aussie Bloke | Casual, friendly Australian male voice | Casual, entertainment |
+| `English_Whispering_girl` | Whispering Girl | Soft, whisper voice | Romance, intimate content |
+| `English_Diligent_Man` | Diligent Man | Hardworking, earnest male voice | Motivational, educational |
+| `English_Gentle-voiced_man` | Gentle-voiced Man | Soft-spoken, kind male voice | Calm, supportive content |
+
+### Japanese Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Japanese_IntellectualSenior` | Intellectual Senior | Wise, knowledgeable elder voice | Narration, educational |
+| `Japanese_DecisivePrincess` | Decisive Princess | Confident, royal princess voice | Animation, games, drama |
+| `Japanese_LoyalKnight` | Loyal Knight | Brave, faithful knight voice | Fantasy, games, stories |
+| `Japanese_DominantMan` | Dominant Man | Powerful, commanding male voice | Action, leadership |
+| `Japanese_SeriousCommander` | Serious Commander | Stern, authoritative commander voice | Military, games |
+| `Japanese_ColdQueen` | Cold Queen | Distant, majestic queen voice | Drama, fantasy |
+| `Japanese_DependableWoman` | Dependable Woman | Reliable, supportive female voice | Supportive, guidance |
+| `Japanese_GentleButler` | Gentle Butler | Polite, refined servant voice | Comedy, animation |
+| `Japanese_KindLady` | Kind Lady | Warm, gentle noblewoman voice | Warm, comforting |
+| `Japanese_CalmLady` | Calm Lady | Composed, serene female voice | Meditation, relaxation |
+| `Japanese_OptimisticYouth` | Optimistic Youth | Cheerful, positive young person voice | Youth content, motivation |
+| `Japanese_GenerousIzakayaOwner` | Generous Izakaya Owner | Friendly, welcoming tavern owner voice | Casual, comedy |
+| `Japanese_SportyStudent` | Sporty Student | Energetic athletic student voice | Sports, youth content |
+| `Japanese_InnocentBoy` | Innocent Boy | Pure, naive young boy voice | Children's content |
+| `Japanese_GracefulMaiden` | Graceful Maiden | Elegant, gentle young woman voice | Romance, drama |
+
+### Korean Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Korean_SweetGirl` | Sweet Girl | Sweet, adorable young girl voice | Children's content, romance |
+| `Korean_CheerfulBoyfriend` | Cheerful Boyfriend | Energetic, loving boyfriend voice | Romance, dating content |
+| `Korean_EnchantingSister` | Enchanting Sister | Charming, captivating sister voice | Family, drama |
+| `Korean_ShyGirl` | Shy Girl | Timid, reserved girl voice | Comedy, romance |
+| `Korean_ReliableSister` | Reliable Sister | Trustworthy, dependable sister voice | Supportive, guidance |
+| `Korean_StrictBoss` | Strict Boss | Authoritative, demanding boss voice | Business, drama |
+| `Korean_SassyGirl` | Sassy Girl | Bold, witty girl voice | Comedy, entertainment |
+| `Korean_ChildhoodFriendGirl` | Childhood Friend Girl | Familiar, friendly childhood friend voice | Romance, nostalgia |
+| `Korean_PlayboyCharmer` | Playboy Charmer | Smooth, flirtatious male voice | Romance, entertainment |
+| `Korean_ElegantPrincess` | Elegant Princess | Graceful, royal princess voice | Animation, fantasy |
+| `Korean_BraveFemaleWarrior` | Brave Female Warrior | Courageous female warrior voice | Action, fantasy |
+| `Korean_BraveYouth` | Brave Youth | Heroic young person voice | Action, youth |
+| `Korean_CalmLady` | Calm Lady | Composed, serene female voice | Meditation, relaxation |
+| `Korean_EnthusiasticTeen` | EnthusiasticTeen | Excited, energetic teenager voice | Youth content |
+| `Korean_SoothingLady` | Soothing Lady | Calming, comforting female voice | Relaxation, support |
+| `Korean_IntellectualSenior` | Intellectual Senior | Wise, knowledgeable elder voice | Educational, narration |
+| `Korean_LonelyWarrior` | Lonely Warrior | Solitary, melancholic warrior voice | Drama, fantasy |
+| `Korean_MatureLady` | MatureLady | Sophisticated, adult female voice | Professional, drama |
+| `Korean_InnocentBoy` | Innocent Boy | Pure, naive young boy voice | Children's content |
+| `Korean_CharmingSister` | Charming Sister | Attractive, delightful sister voice | Family, romance |
+| `Korean_AthleticStudent` | Athletic Student | Sporty, energetic student voice | Sports, youth |
+| `Korean_BraveAdventurer` | Brave Adventurer | Courageous explorer voice | Adventure, fantasy |
+| `Korean_CalmGentleman` | Calm Gentleman | Composed, refined gentleman voice | Formal, professional |
+| `Korean_WiseElf` | Wise Elf | Ancient, mystical elf voice | Fantasy, narration |
+| `Korean_CheerfulCoolJunior` | Cheerful Cool Junior | Popular, friendly junior voice | Youth, entertainment |
+| `Korean_DecisiveQueen` | Decisive Queen | Authoritative, commanding queen voice | Drama, fantasy |
+| `Korean_ColdYoungMan` | Cold Young Man | Distant, aloof young man voice | Drama, romance |
+| `Korean_MysteriousGirl` | Mysterious Girl | Enigmatic, secretive girl voice | Mystery, drama |
+| `Korean_QuirkyGirl` | Quirky Girl | Eccentric, unique girl voice | Comedy, entertainment |
+| `Korean_ConsiderateSenior` | Considerate Senior | Thoughtful, caring elder voice | Warm, supportive |
+| `Korean_CheerfulLittleSister` | Cheerful Little Sister | Playful, adorable younger sister voice | Family, comedy |
+| `Korean_DominantMan` | Dominant Man | Powerful, commanding male voice | Leadership, action |
+| `Korean_AirheadedGirl` | Airheaded Girl | Bubbly, spacey girl voice | Comedy, entertainment |
+| `Korean_ReliableYouth` | Reliable Youth | Trustworthy, dependable young person voice | Supportive, youth |
+| `Korean_FriendlyBigSister` | Friendly Big Sister | Warm, protective elder sister voice | Family, support |
+| `Korean_GentleBoss` | Gentle Boss | Kind, understanding boss voice | Business, supportive |
+| `Korean_ColdGirl` | Cold Girl | Aloof, distant girl voice | Drama, romance |
+| `Korean_HaughtyLady` | Haughty Lady | Arrogant, proud woman voice | Drama, comedy |
+| `Korean_CharmingElderSister` | Charming Elder Sister | Attractive, graceful elder sister voice | Romance, family |
+| `Korean_IntellectualMan` | Intellectual Man | Smart, knowledgeable male voice | Educational, professional |
+| `Korean_CaringWoman` | Caring Woman | Nurturing, supportive woman voice | Supportive, warm |
+| `Korean_WiseTeacher` | Wise Teacher | Experienced, knowledgeable teacher voice | Educational |
+| `Korean_ConfidentBoss` | Confident Boss | Self-assured, capable boss voice | Business, leadership |
+| `Korean_AthleticGirl` | Athletic Girl | Sporty, energetic girl voice | Sports, fitness |
+| `Korean_PossessiveMan` | PossessiveMan | Intense, protective male voice | Romance, drama |
+| `Korean_GentleWoman` | Gentle Woman | Soft-spoken, kind woman voice | Calm, supportive |
+| `Korean_CockyGuy` | Cocky Guy | Confident, slightly arrogant male voice | Comedy, entertainment |
+| `Korean_ThoughtfulWoman` | ThoughtfulWoman | Reflective, caring woman voice | Drama, support |
+| `Korean_OptimisticYouth` | Optimistic Youth | Positive, hopeful young person voice | Motivation, youth |
+
+### Spanish Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Spanish_SereneWoman` | Serene Woman | Calm, peaceful female voice | Relaxation, meditation |
+| `Spanish_MaturePartner` | Mature Partner | Sophisticated, adult partner voice | Romance, drama |
+| `Spanish_CaptivatingStoryteller` | Captivating Storyteller | Engaging, magnetic narrator voice | Audiobooks, storytelling |
+| `Spanish_Narrator` | Narrator | Professional narrative voice | Documentaries, narration |
+| `Spanish_WiseScholar` | Wise Scholar | Knowledgeable, wise scholar voice | Educational, historical |
+| `Spanish_Kind-heartedGirl` | Kind-hearted Girl | Warm, compassionate girl voice | Children's content, warm |
+| `Spanish_DeterminedManager` | Determined Manager | Ambitious, driven manager voice | Business, motivation |
+| `Spanish_BossyLeader` | Bossy Leader | Commanding, authoritative leader voice | Leadership, drama |
+| `Spanish_ReservedYoungMan` | Reserved Young Man | Quiet, introverted young man voice | Drama, realistic characters |
+| `Spanish_ConfidentWoman` | Confident Woman | Self-assured, capable woman voice | Professional, empowerment |
+| `Spanish_ThoughtfulMan` | ThoughtfulMan | Reflective, intelligent man voice | Educational, drama |
+| `Spanish_Strong-WilledBoy` | Strong-willed Boy | Determined, persistent boy voice | Youth, motivation |
+| `Spanish_SophisticatedLady` | SophisticatedLady | Elegant, refined woman voice | Formal, romance |
+| `Spanish_RationalMan` | Rational Man | Logical, analytical man voice | Educational, business |
+| `Spanish_AnimeCharacter` | Anime Character | Exaggerated anime-style voice | Animation, entertainment |
+| `Spanish_Deep-tonedMan` | Deep-toned Man | Deep, resonant male voice | Attractive, commanding |
+| `Spanish_Fussyhostess` | Fussy Hostess | Particular, demanding hostess voice | Comedy, drama |
+| `Spanish_SincereTeen` | SincereTeen | Honest, genuine teenager voice | Youth, authentic |
+| `Spanish_FrankLady` | Frank Lady | Direct, honest woman voice | Comedy, drama |
+| `Spanish_Comedian` | Comedian | Humorous, entertaining voice | Comedy, entertainment |
+| `Spanish_Debator` | Debator | Argumentative, persuasive voice | Debate, discussion |
+| `Spanish_ToughBoss` | Tough Boss | Harsh, demanding boss voice | Business, drama |
+| `Spanish_Wiselady` | Wise Lady | Experienced, wise woman voice | Guidance, advice |
+| `Spanish_Steadymentor` | Steady Mentor | Reliable, supportive mentor voice | Educational, guidance |
+| `Spanish_Jovialman` | Jovial Man | Cheerful, friendly man voice | Entertainment, casual |
+| `Spanish_SantaClaus` | Santa Claus | Festive Santa voice | Holiday, children |
+| `Spanish_Rudolph` | Rudolph | Reindeer voice | Holiday, children |
+| `Spanish_Intonategirl` | Intonate Girl | Musical, melodic girl voice | Music, singing |
+| `Spanish_Arnold` | Arnold | Robotic, mechanical voice | Sci-fi, action |
+| `Spanish_Ghost` | Ghost | Spooky, ethereal voice | Horror, mystery |
+| `Spanish_HumorousElder` | Humorous Elder | Funny, elderly person voice | Comedy, entertainment |
+| `Spanish_EnergeticBoy` | Energetic Boy | Active, lively boy voice | Youth, sports |
+| `Spanish_WhimsicalGirl` | Whimsical Girl | Playful, imaginative girl voice | Children's, fantasy |
+| `Spanish_StrictBoss` | Strict Boss | Strict, demanding boss voice | Business, education |
+| `Spanish_ReliableMan` | Reliable Man | Trustworthy, dependable man voice | Professional, support |
+| `Spanish_SereneElder` | Serene Elder | Calm, peaceful elderly voice | Meditation, wisdom |
+| `Spanish_AngryMan` | Angry Man | Frustrated, irritated male voice | Drama, comedy |
+| `Spanish_AssertiveQueen` | Assertive Queen | Confident, commanding queen voice | Drama, fantasy |
+| `Spanish_CaringGirlfriend` | Caring Girlfriend | Nurturing, loving girlfriend voice | Romance, relationship |
+| `Spanish_PowerfulSoldier` | Powerful Soldier | Strong, brave soldier voice | Action, military |
+| `Spanish_PassionateWarrior` | Passionate Warrior | Fierce, dedicated warrior voice | Action, fantasy |
+| `Spanish_ChattyGirl` | Chatty Girl | Talkative, sociable girl voice | Comedy, social |
+| `Spanish_RomanticHusband` | Romantic Husband | Loving, romantic husband voice | Romance, family |
+| `Spanish_CompellingGirl` | CompellingGirl | Persuasive, magnetic girl voice | Marketing, entertainment |
+| `Spanish_PowerfulVeteran` | Powerful Veteran | Experienced, strong veteran voice | Military, drama |
+| `Spanish_SensibleManager` | Sensible Manager | Practical, reasonable manager voice | Business, guidance |
+| `Spanish_ThoughtfulLady` | Thoughtful Lady | Considerate, kind lady voice | Supportive, advice |
+
+### Portuguese Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Portuguese_SentimentalLady` | Sentimental Lady | Emotional, sensitive lady voice | Drama, romance |
+| `Portuguese_BossyLeader` | Bossy Leader | Commanding, authoritative leader voice | Leadership, drama |
+| `Portuguese_Wiselady` | Wise Lady | Experienced, wise woman voice | Guidance, advice |
+| `Portuguese_Strong-WilledBoy` | Strong-willed Boy | Determined, persistent boy voice | Youth, motivation |
+| `Portuguese_Deep-VoicedGentleman` | Deep-voiced Gentleman | Deep, rich male voice | Attractive, commanding |
+| `Portuguese_UpsetGirl` | Upset Girl | Distressed, emotional girl voice | Drama, realistic |
+| `Portuguese_PassionateWarrior` | Passionate Warrior | Fierce, dedicated warrior voice | Action, fantasy |
+| `Portuguese_AnimeCharacter` | Anime Character | Exaggerated anime-style voice | Animation, entertainment |
+| `Portuguese_ConfidentWoman` | Confident Woman | Self-assured, capable woman voice | Professional, empowerment |
+| `Portuguese_AngryMan` | Angry Man | Frustrated, irritated male voice | Drama, comedy |
+| `Portuguese_CaptivatingStoryteller` | Captivating Storyteller | Engaging, magnetic narrator voice | Audiobooks, storytelling |
+| `Portuguese_Godfather` | Godfather | Authoritative, powerful father figure voice | Drama, powerful |
+| `Portuguese_ReservedYoungMan` | Reserved Young Man | Quiet, introverted young man voice | Drama, realistic |
+| `Portuguese_SmartYoungGirl` | Smart Young Girl | Intelligent, clever girl voice | Educational, youth |
+| `Portuguese_Kind-heartedGirl` | Kind-hearted Girl | Warm, compassionate girl voice | Children's content, warm |
+| `Portuguese_Pompouslady` | Pompous Lady | Self-important, arrogant lady voice | Comedy, drama |
+| `Portuguese_Grinch` | Grinch | Whiny, mischievous voice | Comedy, entertainment |
+| `Portuguese_Debator` | Debator | Argumentative, persuasive voice | Debate, discussion |
+| `Portuguese_SweetGirl` | Sweet Girl | Sweet, adorable girl voice | Children's content, romance |
+| `Portuguese_AttractiveGirl` | Attractive Girl | Charming, appealing girl voice | Entertainment, romance |
+| `Portuguese_ThoughtfulMan` | Thoughtful Man | Reflective, intelligent man voice | Educational, drama |
+| `Portuguese_PlayfulGirl` | Playful Girl | Playful, fun-loving girl voice | Comedy, children's content |
+| `Portuguese_GorgeousLady` | Gorgeous Lady | Beautiful, stunning lady voice | Romance, entertainment |
+| `Portuguese_LovelyLady` | Lovely Lady | Sweet, endearing lady voice | Warm, friendly |
+| `Portuguese_SereneWoman` | Serene Woman | Calm, peaceful female voice | Relaxation, meditation |
+| `Portuguese_SadTeen` | Sad Teen | Melancholic, teenage voice | Drama, emotional |
+| `Portuguese_MaturePartner` | Mature Partner | Sophisticated, adult partner voice | Romance, drama |
+| `Portuguese_Comedian` | Comedian | Humorous, entertaining voice | Comedy, entertainment |
+| `Portuguese_NaughtySchoolgirl` | Naughty Schoolgirl | Mischievous, playful student voice | Comedy, school |
+| `Portuguese_Narrator` | Narrator | Professional narrative voice | Documentaries, narration |
+| `Portuguese_ToughBoss` | Tough Boss | Harsh, demanding boss voice | Business, drama |
+| `Portuguese_Fussyhostess` | Fussy Hostess | Particular, demanding hostess voice | Comedy, drama |
+| `Portuguese_Dramatist` | Dramatist | Theatrical, expressive voice | Drama, storytelling |
+| `Portuguese_Steadymentor` | Steady Mentor | Reliable, supportive mentor voice | Educational, guidance |
+| `Portuguese_Jovialman` | Jovial Man | Cheerful, friendly man voice | Entertainment, casual |
+| `Portuguese_CharmingQueen` | Charming Queen | Elegant, captivating queen voice | Drama, fantasy |
+| `Portuguese_SantaClaus` | Santa Claus | Festive Santa voice | Holiday, children |
+| `Portuguese_Rudolph` | Rudolph | Reindeer voice | Holiday, children |
+| `Portuguese_Arnold` | Arnold | Robotic, mechanical voice | Sci-fi, action |
+| `Portuguese_CharmingSanta` | Charming Santa | Smooth, charismatic Santa voice | Holiday, entertainment |
+| `Portuguese_CharmingLady` | Charming Lady | Elegant, sophisticated lady voice | Professional, romance |
+| `Portuguese_Ghost` | Ghost | Spooky, ethereal voice | Horror, mystery |
+| `Portuguese_HumorousElder` | Humorous Elder | Funny, elderly person voice | Comedy, entertainment |
+| `Portuguese_CalmLeader` | Calm Leader | Composed, steady leader voice | Leadership, guidance |
+| `Portuguese_GentleTeacher` | Gentle Teacher | Kind, patient teacher voice | Educational, supportive |
+| `Portuguese_EnergeticBoy` | Energetic Boy | Active, lively boy voice | Youth, sports |
+| `Portuguese_ReliableMan` | Reliable Man | Trustworthy, dependable man voice | Professional, support |
+| `Portuguese_SereneElder` | Serene Elder | Calm, peaceful elderly voice | Meditation, wisdom |
+| `Portuguese_GrimReaper` | Grim Reaper | Dark, ominous voice | Horror, fantasy |
+| `Portuguese_AssertiveQueen` | Assertive Queen | Confident, commanding queen voice | Drama, fantasy |
+| `Portuguese_WhimsicalGirl` | Whimsical Girl | Playful, imaginative girl voice | Children's, fantasy |
+| `Portuguese_StressedLady` | Stressed Lady | Anxious, overwhelmed lady voice | Comedy, realistic |
+| `Portuguese_FriendlyNeighbor` | Friendly Neighbor | Warm, helpful neighbor voice | Community, family |
+| `Portuguese_CaringGirlfriend` | Caring Girlfriend | Nurturing, loving girlfriend voice | Romance, relationship |
+| `Portuguese_PowerfulSoldier` | Powerful Soldier | Strong, brave soldier voice | Action, military |
+| `Portuguese_FascinatingBoy` | Fascinating Boy | Charming, intriguing boy voice | Romance, youth |
+| `Portuguese_RomanticHusband` | Romantic Husband | Loving, romantic husband voice | Romance, family |
+| `Portuguese_StrictBoss` | Strict Boss | Strict, demanding boss voice | Business, education |
+| `Portuguese_InspiringLady` | Inspiring Lady | Motivating, encouraging lady voice | Motivation, leadership |
+| `Portuguese_PlayfulSpirit` | Playful Spirit | Cheerful, mischievous spirit voice | Fantasy, children's |
+| `Portuguese_ElegantGirl` | Elegant Girl | Graceful, refined girl voice | Formal, romance |
+| `Portuguese_CompellingGirl` | Compelling Girl | Persuasive, magnetic girl voice | Marketing, entertainment |
+| `Portuguese_PowerfulVeteran` | Powerful Veteran | Experienced, strong veteran voice | Military, drama |
+| `Portuguese_SensibleManager` | Sensible Manager | Practical, reasonable manager voice | Business, guidance |
+| `Portuguese_ThoughtfulLady` | Thoughtful Lady | Considerate, kind lady voice | Supportive, advice |
+| `Portuguese_TheatricalActor` | Theatrical Actor | Dramatic, expressive actor voice | Drama, entertainment |
+| `Portuguese_FragileBoy` | Fragile Boy | Sensitive, vulnerable boy voice | Drama, emotional |
+| `Portuguese_ChattyGirl` | Chatty Girl | Talkative, sociable girl voice | Comedy, social |
+| `Portuguese_Conscientiousinstructor` | Conscientious Instructor | Careful, diligent instructor voice | Educational, training |
+| `Portuguese_RationalMan` | Rational Man | Logical, analytical man voice | Educational, business |
+| `Portuguese_WiseScholar` | Wise Scholar | Knowledgeable, wise scholar voice | Educational, historical |
+| `Portuguese_FrankLady` | Frank Lady | Direct, honest woman voice | Comedy, drama |
+| `Portuguese_DeterminedManager` | Determined Manager | Ambitious, driven manager voice | Business, motivation |
+
+### French Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `French_Male_Speech_New` | Level-Headed Man | Calm, reasonable male voice | Professional, narration |
+| `French_Female_News Anchor` | Patient Female Presenter | Clear, patient news presenter voice | News, broadcasts |
+| `French_CasualMan` | Casual Man | Relaxed, informal male voice | Casual, entertainment |
+| `French_MovieLeadFemale` | Movie Lead Female | Dramatic, expressive female voice | Drama, entertainment |
+| `French_FemaleAnchor` | Female Anchor | Professional female anchor voice | News, broadcasts |
+
+### Indonesian Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Indonesian_SweetGirl` | Sweet Girl | Sweet, adorable girl voice | Children's content, friendly |
+| `Indonesian_ReservedYoungMan` | Reserved Young Man | Quiet, introverted young man voice | Drama, realistic |
+| `Indonesian_CharmingGirl` | Charming Girl | Attractive, appealing girl voice | Entertainment, romance |
+| `Indonesian_CalmWoman` | Calm Woman | Composed, peaceful female voice | Relaxation, meditation |
+| `Indonesian_ConfidentWoman` | Confident Woman | Self-assured, capable woman voice | Professional, empowerment |
+| `Indonesian_CaringMan` | Caring Man | Nurturing, supportive man voice | Supportive, family |
+| `Indonesian_BossyLeader` | Bossy Leader | Commanding, authoritative leader voice | Leadership, drama |
+| `Indonesian_DeterminedBoy` | Determined Boy | Ambitious, persistent boy voice | Youth, motivation |
+| `Indonesian_GentleGirl` | Gentle Girl | Soft-spoken, kind girl voice | Calm, supportive |
+
+### German Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `German_FriendlyMan` | Friendly Man | Warm, approachable male voice | Casual, friendly |
+| `German_SweetLady` | Sweet Lady | Pleasant, kind lady voice | Warm, supportive |
+| `German_PlayfulMan` | Playful Man | Fun-loving, humorous male voice | Comedy, entertainment |
+
+### Russian Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Russian_HandsomeChildhoodFriend` | Handsome Childhood Friend | Charming childhood friend voice | Romance, nostalgia |
+| `Russian_BrightHeroine` | Bright Queen | Lively, strong female lead voice | Drama, action |
+| `Russian_AmbitiousWoman` | Ambitious Woman | Driven, determined woman voice | Professional, motivation |
+| `Russian_ReliableMan` | Reliable Man | Trustworthy, dependable man voice | Professional, support |
+| `Russian_CrazyQueen` | Crazy Girl | Wild, unpredictable female voice | Comedy, drama |
+| `Russian_PessimisticGirl` | Pessimistic Girl | Gloomy, negative girl voice | Comedy, drama |
+| `Russian_AttractiveGuy` | Attractive Guy | Charming, appealing male voice | Romance, entertainment |
+| `Russian_Bad-temperedBoy` | Bad-tempered Boy | Irritable, grumpy boy voice | Comedy, drama |
+
+### Italian Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Italian_BraveHeroine` | Brave Heroine | Courageous, heroic female voice | Action, fantasy |
+| `Italian_Narrator` | Narrator | Professional narrative voice | Documentaries, storytelling |
+| `Italian_WanderingSorcerer` | Wandering Sorcerer | Mysterious, traveling magician voice | Fantasy, adventure |
+| `Italian_DiligentLeader` | Diligent Leader | Hardworking, dedicated leader voice | Leadership, business |
+
+### Arabic Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Arabic_CalmWoman` | Calm Woman | Composed, peaceful female voice | Relaxation, meditation |
+| `Arabic_FriendlyGuy` | Friendly Guy | Warm, approachable male voice | Casual, friendly |
+
+### Turkish Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Turkish_CalmWoman` | Calm Woman | Composed, peaceful female voice | Relaxation, meditation |
+| `Turkish_Trustworthyman` | Trustworthy Man | Reliable, sincere male voice | Professional, business |
+
+### Ukrainian Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Ukrainian_CalmWoman` | Calm Woman | Composed, peaceful female voice | Relaxation, meditation |
+| `Ukrainian_WiseScholar` | Wise Scholar | Knowledgeable, wise scholar voice | Educational, historical |
+
+### Dutch Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Dutch_kindhearted_girl` | Kind-hearted girl | Warm, compassionate girl voice | Children's content, warm |
+| `Dutch_bossy_leader` | Bossy leader | Commanding, authoritative leader voice | Leadership, drama |
+
+### Vietnamese Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Vietnamese_kindhearted_girl` | Kind-hearted girl | Warm, compassionate girl voice | Children's content, warm |
+
+### Thai Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Thai_male_1_sample8` | Serene Man | Calm, peaceful male voice | Relaxation, meditation |
+| `Thai_male_2_sample2` | Friendly Man | Warm, approachable male voice | Casual, friendly |
+| `Thai_female_1_sample1` | Confident Woman | Self-assured, capable woman voice | Professional, empowerment |
+| `Thai_female_2_sample2` | Energetic Woman | Active, lively female voice | Motivation, energy |
+
+### Polish Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Polish_male_1_sample4` | Male Narrator | Professional narrative voice | Documentaries, narration |
+| `Polish_male_2_sample3` | Male Anchor | Professional male anchor voice | News, broadcasts |
+| `Polish_female_1_sample1` | Calm Woman | Composed, peaceful female voice | Relaxation, meditation |
+| `Polish_female_2_sample3` | Casual Woman | Relaxed, informal female voice | Casual, entertainment |
+
+### Romanian Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `Romanian_male_1_sample2` | Reliable Man | Trustworthy, dependable man voice | Professional, support |
+| `Romanian_male_2_sample1` | Energetic Youth | Active, lively young person voice | Youth, motivation |
+| `Romanian_female_1_sample4` | Optimistic Youth | Positive, hopeful young person voice | Motivation, youth |
+| `Romanian_female_2_sample1` | Gentle Woman | Soft-spoken, kind woman voice | Calm, supportive |
+
+### Greek Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `greek_male_1a_v1` | Thoughtful Mentor | Reflective, wise mentor voice | Educational, guidance |
+| `Greek_female_1_sample1` | Gentle Lady | Soft-spoken, kind lady voice | Calm, supportive |
+| `Greek_female_2_sample3` | Girl Next Door | Friendly, approachable girl voice | Casual, friendly |
+
+### Czech Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `czech_male_1_v1` | Assured Presenter | Confident, professional presenter voice | Presentations, broadcasts |
+| `czech_female_5_v7` | Steadfast Narrator | Reliable, consistent narrator voice | Documentaries, storytelling |
+| `czech_female_2_v2` | Elegant Lady | Graceful, refined lady voice | Formal, professional |
+
+### Finnish Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `finnish_male_3_v1` | Upbeat Man | Cheerful, energetic male voice | Motivation, entertainment |
+| `finnish_male_1_v2` | Friendly Boy | Warm, approachable boy voice | Children's content, friendly |
+| `finnish_female_4_v1` | Assertive Woman | Confident, strong female voice | Professional, empowerment |
+
+### Hindi Voices
+
+| voice_id | Name | Description | Best For |
+|----------|------|-------------|----------|
+| `hindi_male_1_v2` | Trustworthy Advisor | Reliable, wise advisor voice | Guidance, advice |
+| `hindi_female_2_v1` | Tranquil Woman | Calm, peaceful female voice | Relaxation, meditation |
+| `hindi_female_1_v2` | News Anchor | Professional news anchor voice | News, broadcasts |
+
+---
+
+## Voice Parameters
+
+### VoiceSetting Dataclass
+
+```python
+from utils import VoiceSetting
+
+voice = VoiceSetting(
+    voice_id="male-qn-qingse",  # Required: Voice ID
+    speed=1.0,                   # Optional: 0.5 (slower) to 2.0 (faster), default 1.0
+    volume=1.0,                  # Optional: 0.1 (quieter) to 10.0 (louder), default 1.0
+    pitch=0,                     # Optional: -12 (deeper) to 12 (higher), default 0
+    emotion="calm",           # Optional: happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper
+)
+```
+
+### Parameter Guidelines
+
+**Speed**
+- 0.75: Slower, deliberate speech (news, tutorials)
+- 1.0: Normal pace (most content)
+- 1.25: Slightly faster (energetic content)
+- 1.5+: Fast pace (time-sensitive content)
+
+**Volume**
+- 0.8-1.0: Normal listening levels
+- 1.0-1.5: Louder for attention-grabbing content
+- < 0.8: Softer, intimate feeling
+
+**Pitch**
+- -6 to -3: Deeper, more authoritative
+- 0: Natural pitch
+- +3 to +6: Higher, more energetic
+
+**Emotion**
+- `calm`: Calm, neutral tone
+- `fluent`: Fluent, natural tone
+- `whisper`: Whisper, soft, gentle tone
+- `happy`: Cheerful, upbeat tone
+- `sad`: Melancholic, somber tone
+- `angry`: Frustrated, intense tone
+- `fearful`: Anxious, nervous tone
+- `disgusted`: Repulsed, revolted tone
+- `surprised`: Astonished, amazed tone
+
+
+## Custom Voices
+
+### Voice Cloning
+
+Create custom voices from audio samples for unique brand voices.
+
+**Requirements:**
+- Source audio: 10 seconds to 5 minutes
+- Format: mp3, wav, m4a
+- Size: Max 20MB
+- Quality: Clear, no background noise, single speaker
+
+**Best Practices:**
+- Use 30-60 seconds of clean speech
+- Include varied intonation and emotion
+- Record in quiet environment
+- Consistent volume throughout
+
+### Voice Design
+
+Generate new voices through text descriptions for creative projects.
+
+**When to Use:**
+- No existing voice matches your needs
+- Need unique character voices
+- Prototype before full voice cloning
+
+**Prompt Guidelines:**
+- Include: gender, age, vocal characteristics, emotional tone, use case
+- Be specific about pacing, tone, and intended audience
+- Example: "A warm, grandmotherly voice with gentle pacing, perfect for bedtime stories"
+
--- a/frontend-dev/references/motion-recipes.md
+++ b/frontend-dev/references/motion-recipes.md
@@ -0,0 +1,407 @@
+# Motion Recipes
+
+Production-ready animation code snippets. Copy and adapt as needed.
+
+## 1. Scroll-Triggered Reveal (Framer Motion)
+
+Elements fade and slide up when entering viewport.
+
+```tsx
+"use client";
+import { motion } from "framer-motion";
+
+const fadeSlideUp = {
+  hidden: { opacity: 0, y: 40 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    transition: { type: "spring", stiffness: 100, damping: 20 },
+  },
+};
+
+export function RevealSection({ children }: { children: React.ReactNode }) {
+  return (
+    <motion.div
+      variants={fadeSlideUp}
+      initial="hidden"
+      whileInView="visible"
+      viewport={{ once: true, margin: "-80px" }}
+    >
+      {children}
+    </motion.div>
+  );
+}
+```
+
+## 2. Staggered List Orchestration (Framer Motion)
+
+Children animate sequentially with blur effect.
+
+```tsx
+"use client";
+import { motion } from "framer-motion";
+
+const container = {
+  hidden: {},
+  visible: { transition: { staggerChildren: 0.08, delayChildren: 0.1 } },
+};
+
+const item = {
+  hidden: { opacity: 0, y: 24, filter: "blur(4px)" },
+  visible: {
+    opacity: 1,
+    y: 0,
+    filter: "blur(0px)",
+    transition: { type: "spring", stiffness: 120, damping: 20 },
+  },
+};
+
+export function StaggerGrid({ items }: { items: React.ReactNode[] }) {
+  return (
+    <motion.div
+      className="grid gap-6"
+      variants={container}
+      initial="hidden"
+      whileInView="visible"
+      viewport={{ once: true }}
+    >
+      {items.map((child, i) => (
+        <motion.div key={i} variants={item}>
+          {child}
+        </motion.div>
+      ))}
+    </motion.div>
+  );
+}
+```
+
+## 3. GSAP ScrollTrigger Pinned Section
+
+Horizontal scroll panels with pinning.
+
+```tsx
+"use client";
+import { useRef, useEffect } from "react";
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+gsap.registerPlugin(ScrollTrigger);
+
+export function PinnedTimeline() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const panelsRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const ctx = gsap.context(() => {
+      const panels = gsap.utils.toArray<HTMLElement>(".panel");
+      gsap.to(panels, {
+        xPercent: -100 * (panels.length - 1),
+        ease: "none",
+        scrollTrigger: {
+          trigger: containerRef.current,
+          pin: true,
+          scrub: 1,
+          end: () => "+=" + (panelsRef.current?.scrollWidth ?? 0),
+        },
+      });
+    }, containerRef);
+
+    return () => ctx.revert(); // CRITICAL: full cleanup
+  }, []);
+
+  return (
+    <div ref={containerRef} className="overflow-hidden">
+      <div ref={panelsRef} className="flex">
+        {/* .panel elements */}
+      </div>
+    </div>
+  );
+}
+```
+
+## 4. Parallax Tilt Card (Framer Motion)
+
+Mouse-tracking 3D perspective. Uses `useMotionValue` — never `useState`.
+
+```tsx
+"use client";
+import { motion, useMotionValue, useTransform } from "framer-motion";
+
+export function TiltCard({ children }: { children: React.ReactNode }) {
+  const x = useMotionValue(0.5);
+  const y = useMotionValue(0.5);
+  const rotateX = useTransform(y, [0, 1], [8, -8]);
+  const rotateY = useTransform(x, [0, 1], [-8, 8]);
+
+  return (
+    <motion.div
+      style={{ rotateX, rotateY, transformPerspective: 800 }}
+      onMouseMove={(e) => {
+        const rect = e.currentTarget.getBoundingClientRect();
+        x.set((e.clientX - rect.left) / rect.width);
+        y.set((e.clientY - rect.top) / rect.height);
+      }}
+      onMouseLeave={() => {
+        x.set(0.5);
+        y.set(0.5);
+      }}
+      className="rounded-2xl bg-white shadow-lg"
+    >
+      {children}
+    </motion.div>
+  );
+}
+```
+
+## 5. Magnetic Button (Framer Motion)
+
+Cursor-attracted button. Pure `useMotionValue` — zero re-renders.
+
+```tsx
+"use client";
+import { motion, useMotionValue, useSpring } from "framer-motion";
+import { useRef } from "react";
+
+export function MagneticButton({ children }: { children: React.ReactNode }) {
+  const ref = useRef<HTMLButtonElement>(null);
+  const x = useMotionValue(0);
+  const y = useMotionValue(0);
+  const springX = useSpring(x, { stiffness: 200, damping: 15 });
+  const springY = useSpring(y, { stiffness: 200, damping: 15 });
+
+  return (
+    <motion.button
+      ref={ref}
+      style={{ x: springX, y: springY }}
+      onMouseMove={(e) => {
+        const rect = ref.current!.getBoundingClientRect();
+        const dx = e.clientX - (rect.left + rect.width / 2);
+        const dy = e.clientY - (rect.top + rect.height / 2);
+        x.set(dx * 0.3);
+        y.set(dy * 0.3);
+      }}
+      onMouseLeave={() => {
+        x.set(0);
+        y.set(0);
+      }}
+    >
+      {children}
+    </motion.button>
+  );
+}
+```
+
+## 6. Text Scramble / Decode Effect
+
+Matrix-style character reveal — pure JS, no library needed.
+
+```tsx
+"use client";
+import { useEffect, useRef, useState } from "react";
+
+const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+export function TextScramble({ text, className }: { text: string; className?: string }) {
+  const [display, setDisplay] = useState(text);
+  const iteration = useRef(0);
+
+  useEffect(() => {
+    iteration.current = 0;
+    const id = setInterval(() => {
+      setDisplay(
+        text
+          .split("")
+          .map((char, i) =>
+            i < iteration.current ? char : chars[Math.floor(Math.random() * chars.length)]
+          )
+          .join("")
+      );
+      iteration.current += 1 / 3;
+      if (iteration.current >= text.length) clearInterval(id);
+    }, 30);
+    return () => clearInterval(id);
+  }, [text]);
+
+  return <span className={className}>{display}</span>;
+}
+```
+
+## 7. SVG Path Draw on Scroll (CSS Scroll-Driven)
+
+Zero-JS scroll-linked path drawing using native CSS.
+
+```css
+@supports (animation-timeline: scroll()) {
+  .draw-path {
+    stroke-dasharray: 1;
+    stroke-dashoffset: 1;
+    animation: draw linear;
+    animation-timeline: scroll();
+    animation-range: entry 0% cover 60%;
+  }
+
+  @keyframes draw {
+    to {
+      stroke-dashoffset: 0;
+    }
+  }
+}
+```
+
+## 8. Horizontal Scroll Hijack (GSAP)
+
+Vertical scroll drives horizontal panning.
+
+```tsx
+"use client";
+import { useRef, useEffect } from "react";
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+gsap.registerPlugin(ScrollTrigger);
+
+export function HorizontalScroll({ children }: { children: React.ReactNode }) {
+  const sectionRef = useRef<HTMLDivElement>(null);
+  const trackRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const ctx = gsap.context(() => {
+      const track = trackRef.current!;
+      const scrollWidth = track.scrollWidth - window.innerWidth;
+      gsap.to(track, {
+        x: -scrollWidth,
+        ease: "none",
+        scrollTrigger: {
+          trigger: sectionRef.current,
+          pin: true,
+          scrub: 0.8,
+          end: () => `+=${scrollWidth}`,
+        },
+      });
+    }, sectionRef);
+    return () => ctx.revert();
+  }, []);
+
+  return (
+    <section ref={sectionRef} className="overflow-hidden">
+      <div ref={trackRef} className="flex gap-8 w-max">
+        {children}
+      </div>
+    </section>
+  );
+}
+```
+
+## 9. Particle Background (React Three Fiber)
+
+Isolated canvas layer. Purely decorative, pointer-events-none.
+
+```tsx
+"use client";
+import { Canvas, useFrame } from "@react-three/fiber";
+import { useRef, useMemo } from "react";
+import * as THREE from "three";
+
+function Particles({ count = 800 }) {
+  const mesh = useRef<THREE.Points>(null);
+  const positions = useMemo(() => {
+    const arr = new Float32Array(count * 3);
+    for (let i = 0; i < count * 3; i++) arr[i] = (Math.random() - 0.5) * 10;
+    return arr;
+  }, [count]);
+
+  useFrame(({ clock }) => {
+    if (mesh.current) mesh.current.rotation.y = clock.getElapsedTime() * 0.05;
+  });
+
+  return (
+    <points ref={mesh}>
+      <bufferGeometry>
+        <bufferAttribute attach="attributes-position" args={[positions, 3]} />
+      </bufferGeometry>
+      <pointsMaterial size={0.015} color="#94a3b8" transparent opacity={0.6} />
+    </points>
+  );
+}
+
+export function ParticleCanvas() {
+  return (
+    <div className="fixed inset-0 -z-10 pointer-events-none">
+      <Canvas camera={{ position: [0, 0, 5], fov: 60 }}>
+        <Particles />
+      </Canvas>
+    </div>
+  );
+}
+```
+
+## 10. Shared Layout Morph (Framer Motion)
+
+Card-to-modal expansion using `layoutId`.
+
+```tsx
+"use client";
+import { motion, AnimatePresence } from "framer-motion";
+import { useState } from "react";
+
+export function MorphCard({ id, preview, detail }: {
+  id: string;
+  preview: React.ReactNode;
+  detail: React.ReactNode;
+}) {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <motion.div layoutId={`card-${id}`} onClick={() => setOpen(true)}
+        className="cursor-pointer rounded-2xl bg-white p-6 shadow-md">
+        {preview}
+      </motion.div>
+
+      <AnimatePresence>
+        {open && (
+          <>
+            <motion.div
+              initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
+              className="fixed inset-0 bg-black/40 z-40"
+              onClick={() => setOpen(false)}
+            />
+            <motion.div layoutId={`card-${id}`}
+              className="fixed inset-4 md:inset-20 z-50 rounded-2xl bg-white p-8 shadow-2xl overflow-auto">
+              {detail}
+            </motion.div>
+          </>
+        )}
+      </AnimatePresence>
+    </>
+  );
+}
+```
+
+## Scroll Animation Patterns
+
+### Sticky Scroll Stack
+Cards pin to top and stack over each other.
+- Each card: `position: sticky; top: calc(var(--index) * 2rem)`
+- Depth illusion: `scale(calc(1 - var(--index) * 0.03))`
+
+### Split-Screen Parallax
+Two viewport halves scroll at different speeds.
+- Left: `translateY` at 0.5x scroll speed (GSAP `scrub`)
+- Mobile: collapse to single column, disable parallax
+
+### Zoom Parallax
+Hero image scales 1 to 1.5 on scroll.
+```tsx
+scrollTrigger: { trigger: heroRef, start: "top top", end: "bottom top", scrub: true }
+gsap.to(imageRef, { scale: 1.5, ease: "none" });
+```
+
+### Text Mask Reveal
+Large typography as window into video/image background.
+- `background-clip: text` + `color: transparent`
+- Animate `background-position` on scroll
+
+### Curtain Reveal
+Hero splits in half, each side slides away on scroll.
+- Two halves clipped with `clip-path: inset(0 50% 0 0)` and `inset(0 0 0 50%)`
+- GSAP animates `xPercent: -100` and `xPercent: 100`
--- a/frontend-dev/references/troubleshooting.md
+++ b/frontend-dev/references/troubleshooting.md
@@ -0,0 +1,85 @@
+# Troubleshooting
+
+## Quick reference
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `MINIMAX_API_KEY is not set` | Key not set | `export MINIMAX_API_KEY="key"` |
+| `401 Unauthorized` | Invalid/expired key | Check key validity |
+| `429 Too Many Requests` | Rate limit | Add delays between requests |
+| `TimeoutError` | Network or long text | Use async TTS for long text, check network |
+| `invalid params, method t2a-v2 not have model` | Wrong model name | Use `speech-2.8-hd` (hyphens, not underscores) |
+| `brotli: decoder process called...` | Encoding issue | Already fixed in utils.py (Accept-Encoding header) |
+
+## Environment
+
+### API key not set
+
+```bash
+export MINIMAX_API_KEY="<paste-your-key-here>"
+
+# Verify
+echo $MINIMAX_API_KEY
+```
+
+### FFmpeg not found
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu
+sudo apt install ffmpeg
+
+# Verify
+ffmpeg -version
+```
+
+### Missing Python packages
+
+```bash
+pip install requests
+```
+
+## API errors
+
+### Authentication (401)
+
+- Verify API key is correct and not expired
+- Check for extra spaces in key value
+
+### Rate limiting (429)
+
+Add delays between requests:
+```python
+import time
+for text in texts:
+    result = tts(text)
+    time.sleep(1)
+```
+
+### Invalid model name
+
+Valid names (use hyphens, must include -hd or -turbo):
+- `speech-2.8-hd` (recommended)
+- `speech-2.8-turbo`
+- `speech-2.6-hd`
+- `speech-2.6-turbo`
+
+Wrong: `speech_01`, `speech_2.6`, `speech-01`
+
+## Audio issues
+
+### Poor quality
+
+Re-generate with higher settings:
+```bash
+python scripts/minimax_tts.py "text" -o out.mp3 --sample-rate 32000 --model speech-2.8-hd
+```
+
+### Invalid emotion
+
+Valid emotions:
+- All models: happy, sad, angry, fearful, disgusted, surprised, calm
+- speech-2.6 only: + fluent, whisper
+- speech-2.8: auto-matched (leave empty, recommended)