Music: your agent writes an original song from a prompt

A song in one call

generate_music gives an agent a composer. The agent describes the song in plain language — genre, tempo, mood, instrumentation, and the lyrics if it wants vocals — and gets back an original song, saved where the rest of its work is. It sits next to speech and sound effects in the audio tools: speech says a line, a sound effect is a few seconds of foley or ambience, and a song is music with a structure, up to five minutes long.

The call takes three arguments:

• prompt. What the song should sound like, 1 to 2,000 characters.
• length_seconds. Optional, 3 to 300. Left out, the song is 30 seconds.
• instrumental. Optional. True forces a track with no vocals.

There is no model to pick and no voice to name. The tool runs on one generator and the reply names none.

The call is synchronous. The generator answers the song inside the call, so there is no job id to remember and nothing to collect later. When it returns, the song is already saved.

Where the song goes

The song lands in Files as a fil_ mp3, with its prompt and its duration recorded in the library. The tool returns the file's id, name, size, duration and checksum.

It never lands on the agent's computer. That is deliberate. A song is an ingredient: the agent passes its id to the next step, and the tool's own reply tells the agent that the song is stored, that it should not publish it, and that it should not generate it again. An agent that wants to work on the audio — cut it, mix it, lay it under a picture — fetches the file onto its computer and uses the tools already there.

That is exactly what the music channel templates do. A short-video app takes no audio-only post, so the song alone cannot be posted. The agent fetches the song and a square cover onto its computer, runs one ffmpeg command, and gets a 1080x1920 video of the cover held over the song. That video is what goes up for approval.

How an agent uses it

generate_music is a built-in tool, granted like any other. A good prompt says the sound in musical words rather than by naming a performer:

• Tempo and genre. "Hypnotic techno, 132 BPM."
• The parts. "A rumbling kick, a tight closed hat, a repeating acid bass line."
• What it is about. One sentence, for the lyric or the mood.
• What it must not be. "No vocals. Original composition, not based on any existing song or artist."

The agent calls the tool once per song. A song that came back as a file is never generated a second time: a new version is a new song, and a new charge. Where the result should have no singing, the agent sets instrumental rather than hoping the prompt is read that way.

Priced by the seconds generated

A song is billed on the media component, at what the generator charged for the seconds of music it made. The cost is settled from the song that actually comes back, after the audio lands, and booked once. A call that fails books nothing. No per-song price is published, for the same reason there is no per-model table for images or video: the cost is the generator's, read from the finished call, and it comes back on the call as cost_micro_usd over REST.

Like every media call, a song is booked after the fact. Watch the media component of an agent's spend to see what its songs cost. The agent's cap and the organization's balance are the real limits. Over REST, an empty balance is refused with 402 insufficient_credits before anything is sent to the generator.

Every surface

Inside a session it is the generate_music tool. Over REST it is POST /v1/media/music, with the agents:write scope and an Idempotency-Key, which makes a retry with the same key safe. The SDK method is client.media.music.generate. The CLI command is naive media music "<prompt>", with --seconds and --instrumental. The same call is an MCP tool, so an external client drives it the way an agent does. The Music primitive has the details.

The AI Music Channel

The first templates built on it are the AI Music Channel and its four genres, coming soon. Each is an agent team: a composer writes one song a day at most from the channel's context seed, a cover-artist makes a square cover and turns the two into one short vertical video, a channel manager files the post for your approval, and an analyst reads the numbers.

The genre templates pin the seed, so the sound never drifts:

• Hardstyle. 155 BPM, a distorted kick, a reverse bass, a drop inside the first eight seconds. No vocals.
• Techno. 132 BPM, a rumbling kick and a slow acid loop. No festival drop.
• Rap. 90 BPM, dry drums, an 808, one sung hook and one verse of original lyrics.
• Pop. 110 BPM, bright chords and a sung hook you can hum.

Every song on those channels is original. The team never names a real artist as the style, never copies a commercial track, and never posts before a person approves it. No AI label is added to a caption or a post unless the owner asks for one.