media-generation-skill

name	media-generation-skill
version	1.0.0
description	Expert knowledge for AI media generation — image prompting, video workflows, music composition, and TTS best practices
runtime	prompt_only

Media Generation Expert Knowledge

Tool Reference

image_generate

Generate images from text prompts via OpenAI or MiniMax.

Parameters:

Parameter	Type	Required	Default	Description
prompt	string	yes	—	Text description of the desired image
provider	string	no	auto	openai or minimax
model	string	no	provider default	gpt-image-1, dall-e-3, image-01
width	int	no	1024	Image width in pixels
height	int	no	1024	Image height in pixels
count	int	no	1	Number of images (1-4)
quality	string	no	auto	low, medium, high, auto
seed	int	no	random	Reproducibility seed

Provider-specific notes:

• OpenAI gpt-image-1: Best for photorealistic and creative images. Supports inpainting hints in prompt. Sizes: 1024x1024, 1792x1024, 1024x1792.
• OpenAI dall-e-3: Good quality, may revise your prompt (check revised_prompt in response). Only generates 1 image per call.
• MiniMax image-01: Fast generation, good for illustrations and concept art. Supports arbitrary aspect ratios.

Result: Returns images array with url fields pointing to /api/uploads/{id}.

---

text_to_speech

Convert text to spoken audio.

Parameters:

Parameter	Type	Required	Default	Description
text	string	yes	—	Text to speak (max ~4096 chars per call)
provider	string	no	auto	openai or minimax
model	string	no	provider default	tts-1, tts-1-hd, speech-2.8-hd
voice	string	no	alloy	Voice selection (see table below)
speed	float	no	1.0	Playback speed (0.25 - 4.0)
format	string	no	mp3	mp3, wav, flac, opus, aac

OpenAI voices:

Voice	Character
alloy	Neutral, balanced
echo	Male, warm
fable	Storytelling, expressive
nova	Female, friendly
onyx	Deep male, authoritative
shimmer	Warm female, gentle

MiniMax voices:

Voice	Character
English_Graceful_Lady	Female, elegant
English_Calm_Man	Male, composed
English_Energetic_Girl	Female, upbeat

Tips:

• For long content, split at paragraph boundaries to keep natural pacing
• tts-1-hd is higher quality but slower; use tts-1 for drafts
• Speed 0.8-0.9 works well for narration; 1.1-1.2 for summaries

Result: Returns url to the audio file, format, duration_ms, sample_rate.

---

video_generate

Submit an asynchronous video generation task. Video generation takes 1-3 minutes.

Parameters:

Parameter	Type	Required	Default	Description
prompt	string	yes	—	Scene description
provider	string	no	auto	Currently only minimax
model	string	no	T2V-01	Video model
duration_secs	int	no	5	Video duration (5-10 seconds)
resolution	string	no	1080p	720p, 1080p

Prompt writing for video:

• Be specific about the scene, subject, and action
• Describe camera movement explicitly: "slow pan left", "zoom in", "static shot"
• Keep it focused — one scene per generation works best
• Include lighting and atmosphere: "golden hour lighting", "neon-lit street at night"
• Avoid complex multi-character interactions (current models handle single subjects best)

Good prompts:

• "A golden retriever running through a wheat field at sunset, slow motion, cinematic"
• "Close-up of coffee being poured into a ceramic cup, steam rising, warm morning light"
• "Aerial drone shot flying over a tropical coastline, turquoise water, white sand beach"

Bad prompts:

• "A video" (too vague)
• "Two people having a conversation at a cafe while a dog runs by and a car crashes outside" (too complex)

Result: Returns task_id and provider. You MUST poll with video_status.

---

video_status

Poll the status of a video generation task.

Parameters:

Parameter	Type	Required	Description
task_id	string	yes	From video_generate response
provider	string	yes	Must match the provider from video_generate

Statuses:

Status	Meaning	Action
pending	Queued, not started	Wait 10-15s, poll again
processing	Actively generating	Wait 15-20s, poll again
completed	Done	Result includes file_url
failed	Generation failed	Check error message, may retry with different prompt

Polling pattern:

1. Call video_generate → get task_id
2. Wait 10 seconds
3. Call video_status with task_id + provider
4. If not completed, wait 15-20 seconds and poll again
5. Maximum ~10 polls (about 3 minutes total)
6. Always inform the user of current status

Result (completed): Returns file_url, width, height, duration_secs, provider, model.

---

music_generate

Generate music from a text prompt and/or lyrics.

Parameters:

Parameter	Type	Required	Default	Description
prompt	string	no*	—	Style/mood description
lyrics	string	no*	—	Song lyrics with structure
provider	string	no	auto	Currently only minimax
model	string	no	music-2.5	Music model
instrumental	bool	no	false	Generate without vocals
format	string	no	mp3	mp3, wav, flac

*At least one of prompt or lyrics is required.

Prompt writing for music:

For instrumentals, describe:

• Genre: electronic, jazz, classical, hip-hop, rock, ambient, lo-fi
• Tempo: slow (60-80 BPM), medium (100-120 BPM), fast (130-160 BPM)
• Mood: uplifting, melancholic, energetic, relaxing, dramatic, mysterious
• Instruments: piano, synth, acoustic guitar, strings, drums, bass

For songs with vocals, provide lyrics with structure markers:

[Verse 1]
Walking down the empty street
Moonlight dancing at my feet

[Chorus]
This is where the night begins
Let the music pull us in

[Verse 2]
...

Good prompts:

• prompt: "Chill lo-fi hip-hop beat, vinyl crackle, mellow piano chords, 85 BPM, rainy day vibe"
• prompt: "Epic orchestral trailer music, building tension, brass and strings, 140 BPM"
• prompt + lyrics: "Indie folk acoustic ballad, fingerpicking guitar, gentle male vocals" with lyrics

Result: Returns url to audio file, format, duration_ms, sample_rate.

---

Combined Workflow Recipes

Podcast Intro

1. music_generate — instrumental jingle, 10-15 seconds, upbeat
2. text_to_speech — "Welcome to [show name]..." with energetic voice
3. Report both URLs to user

Social Media Post

1. image_generate — eye-catching visual for the post
2. Suggest caption text based on the image
3. Optionally text_to_speech for accessibility audio version

Video with Narration

1. text_to_speech — generate narration audio
2. video_generate — generate matching video clip
3. video_status — poll until complete
4. Report both URLs (user can combine with ffmpeg or editing tools)

Album Art + Preview

1. image_generate — album cover artwork
2. music_generate — short preview track matching the artwork mood
3. Present together

Audiobook Chapter

1. Split text into sections (~500 words each)
2. text_to_speech for each section with consistent voice
3. Report all audio URLs in order

---

Error Handling

Error	Cause	Fix
missing_key	API key not configured	Ask user to set OPENAI_API_KEY or MINIMAX_API_KEY
not_supported	Provider doesn't support this modality	Switch to a provider that does
content_filtered	Safety filter rejected the prompt	Rephrase without prohibited content
rate_limited	Too many requests	Wait 30-60 seconds and retry
invalid_request	Bad parameters	Check parameter ranges (e.g., count 1-4, speed 0.25-4.0)

---

Provider Capability Matrix

Capability	OpenAI	MiniMax
Image generation	gpt-image-1, dall-e-3	image-01
Text-to-speech	tts-1, tts-1-hd	speech-2.8-hd
Video generation	—	T2V-01, video-01
Music generation	—	music-2.5

Auto-detection priority: OpenAI > MiniMax (for capabilities both support). If only MiniMax key is set, all 4 modalities are available through MiniMax.