gemini_music_generate
Create music from text by describing mood, genre, instruments, or lyrics, and receive an MP3 or WAV file. Async mode prevents timeouts on long generations.
Instructions
Generate music from a text prompt (mood, genre, instruments, structure, or lyrics inline) via a Lyria model (preview): lyria-3-clip-preview (~30s clips, default) or lyria-3-pro-preview (longer, WAV-capable). Written to disk as MP3/WAV (or returned inline). Runs long — use async: true + gemini_get_result, or raise timeout_ms. Preview model: needs a funded account.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| async | No | Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off. | |
| model | No | Lyria model (default: lyria-3-clip-preview). Pro is longer-form and supports WAV. | |
| images | No | Optional reference image path(s) to condition the music | |
| inline | No | Return base64 audio inline instead of writing to disk | |
| prompt | Yes | Description of the music: mood, genre, instruments, tempo, structure, or lyrics | |
| confirm | No | Must be true to proceed. Without this, the tool returns a preview. | |
| filename | No | Base filename for the output audio (extension stripped; default: slugified prompt) | |
| background | No | Run the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Off by default — see gemini_video_generate | |
| images_url | No | Reference images as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*). | |
| output_dir | No | Directory to write audio to (default: $GEMINI_OUTPUT_DIR or cwd) | |
| timeout_ms | No | Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s) | |
| max_wait_ms | No | Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: "running" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set. | |
| audio_format | No | Output format (default mp3). wav is lyria-3-pro-preview-only. | |
| continue_last | No | Continue from the most recent music interaction this server created (explicit previous_interaction_id wins) | |
| images_base64 | No | Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation | |
| from_clipboard | No | Use the image currently on the macOS clipboard as a reference | |
| idempotency_key | No | Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge. | |
| images_file_uris | No | Reference images by Gemini Files API reference ("files/<id>", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving. | |
| previous_interaction_id | No | Interaction id to continue from |