audio-generation

name

audio_generation

description

Generate audio in two ways: text-to-speech, or custom sound effects. ### Speech (text-to-speech): - High-quality text-to-speech conversion using a selected voice - Several pre-built Mandarin voices with different characteristics - Use clear, well-formatted text (punctuation helps natural speech) ### Sound effects: - AI-powered sound effect generation from an English description - Customizable duration (0.5 to 22 seconds) - Covers ambient, action, musical, foley, emotional, and abstract sounds - The description MUST be in English ### Usage Guidelines: - For speech: pick a voice ID and provide the text to read - For sound effects: give a detailed English description and a duration - Specify an output path with a .mp3 extension - Output is saved locally as mp3

Audio Generation

Use this skill to generate audio. There are two distinct flows — pick the one that matches the user's intent:

• Generate speech (text-to-speech): the user wants spoken audio of some text. Use the speech flow.
• Generate sound effects: the user wants a sound effect / ambience / SFX described in words. Use the sound-effects flow.

Setup

Before the first use, ensure the agent-gw Python SDK (version 0.2.6 or newer) is installed. This checks the current environment and installs or upgrades it only when needed:

python3 scripts/audio_generation_tool.py ensure-deps

The SDK needs an API key from api_key=..., KIMI_API_KEY, or ~/.kimi/agent-gw.json.

Choosing the flow

1. If the user wants their text read aloud / a voiceover / TTS → speech.
2. If the user wants a sound effect, ambience, music bed, or SFX described in words → sound-effects.

Then build the parameters for that flow, run the matching command, and on success surface the saved mp3 to the user. On failure, explain the error from the script; do not invent audio or a local path.

Flow A — Generate speech (text-to-speech)

Parameters:

• text (required): the text to convert to speech.
• voice_id (required): one of the supported voices below. Default is 05Cdh2gw2NMzDvykn1nm.
• output (required): local output path ending in .mp3.

Supported voice IDs:

• 05Cdh2gw2NMzDvykn1nm: calm middle-aged Mandarin male (default)
• Q63G7WZ5riIGbK8KmqO9: energetic young Mandarin male
• NLl76XZRVj1RVeXptX3h: warm Mandarin female
• At6gj9vUVdJhTriBsuxE: cheerful Mandarin female

Best practices: use punctuation and formatting for natural speech, and break long texts into smaller segments for better quality.

python3 scripts/audio_generation_tool.py speech \
  --text "你好，欢迎使用 Kimi。" \
  --voice-id "05Cdh2gw2NMzDvykn1nm" \
  --output "/path/to/output.mp3"

This sends {"text", "voice_id"} to the gateway generate_speech API.

Flow B — Generate sound effects

Parameters:

• description (required): a detailed description of the sound effect. It MUST be in English — never use another language.
• duration (required): duration in seconds, range 0.5-22.
• output (required): local output path ending in .mp3.

Duration guidance: short (0.5-3s) for UI sounds/notifications, medium (3-10s) for ambient loops or action sequences, long (10-22s) for background music or extended ambience.

python3 scripts/audio_generation_tool.py sound-effects \
  --description "Gentle rain falling on leaves with distant thunder" \
  --duration 8 \
  --output "/path/to/output.mp3"

This sends {"description", "duration_seconds"} to the gateway generate_sound_effects API.

After generation

Both flows read media.url / media.mime_type from the response and download the audio to your output path with curl (allowing up to 5 minutes). The script then prints the saved mp3 path. Surface that audio to the user (e.g. via the readFile tool on the path). Playing or reading the audio to present it is the model's job, not this plugin's work.

Script summary

The script:

• speech validates voice_id against the supported list and sends {"text", "voice_id"} to generate_speech
• sound-effects validates the duration is within 0.5-22 and sends {"description", "duration_seconds"} to generate_sound_effects
• reads the generated media.url and media.mime_type from the response
• downloads the audio to the --output path with curl (up to 5 minutes), naming the file as .mp3
• prints the saved path and a reminder to surface it to the user

Response shape for both APIs (resp.json()):

{
    "media": {
        "url": str,        # public URL of the generated audio
        "mime_type": str,  # e.g. "audio/mpeg"
    }
}

This skill uses the agent-gw Python SDK: client.tools.generate_speech(text, voice_id=...) and client.tools.generate_sound_effects(description, duration_seconds=...), with the response shape above.