メインコンテンツへスキップ
The AI Gateway serves a music endpoint, so your app can turn a text prompt into a song or an instrumental track, with control over its style, lyrics, and length. Requests are billed to your app’s credits, with no separate provider account or API key.
Before you begin:
  • Call the gateway server-side, such as from a backend function, rather than the browser. This lets you check who’s calling and control usage before a request is billed to your app.
  • Get the baseURL, token, and headers from base44.asServiceRole.aiGateway.connection().
  • Calls from the browser or with a user’s token get a 403 and the error code ai_gateway_requires_service_role.
Music generation is synchronous. The request stays open until the track is ready, which can take a minute or more, and then returns a link to the finished MP3. There’s no job to poll.

Endpoint

The endpoint accepts JSON. Authenticate with Authorization: Bearer {token}. OpenAI’s API has no music endpoint, so the request and response format is Base44’s own, and errors follow OpenAI’s format like the rest of the gateway.

Generate a song

Send a prompt that describes the style and mood, and any lyrics, to POST /audio/music. The gateway stores the MP3 in your app’s files and returns its url.
Generate a song
Save song.url on an entity rather than downloading the file and uploading it again. The file is already in your app’s storage. To use the OpenAI SDK instead of fetch(), call the endpoint with client.post(). Set a long timeout so the client waits for the track, and turn off automatic retries so a slow request isn’t sent and billed twice.
Generate a song with the OpenAI SDK

Write the prompt

The prompt carries everything about the track, including its genre, mood, instruments, tempo, and lyrics. Mark lyric sections with tags such as [Verse] and [Chorus].
Prompt with lyrics
Music generation takes no image or audio input. To write a song about a photo or a story, first send the image or text to a chat model and ask it for short lyrics and a style description, then put them in the music prompt.
Don’t name a real artist or include copyrighted lyrics. The model refuses these prompts, and the request fails with a 400.

Instrumental tracks

Set instrumental to true to ask for a track without vocals. On lyria_3_5, this is best effort, and the track can still have vocals. Leave lyrics out of the prompt for an instrumental track.

Duration

Set duration_seconds to a whole number from 5 to 180. It defaults to 30. On lyria_3_5, the duration is a target rather than an exact length, and the track can run longer than you asked. The duration_seconds in the response is the length you requested, not the length of the file.

Models

Set model to automatic or leave it out to let Base44 choose, or pin a model ID. automatic always uses lyria_3_5. Music models are separate from the chat models, image models, and video models the gateway serves.

Play the track

The url points to an MP3 file, so you can play it like any other audio file. On the web, render it with an <audio> element.
Play a generated song
Browsers often block autoplay, so let the person start playback. Because generation takes a while, show a loading state in your app while the backend function waits for the track.

Request parameters

Fields that aren’t listed here are ignored.

Response

The url points to a file stored in your app’s public file storage.

Estimate the cost

Set dry_run to true to see which model a request would run on and what it would cost, without generating a track or using credits.
Estimate the cost of a request
Music requests use your app’s credits, the same shared quota as the rest of the AI Gateway. lyria_3_5 is billed per track, so a longer track costs the same as a shorter one. A request that fails isn’t billed.

Limits

Errors

Errors use OpenAI’s format, { "error": { "message", "type", "code", "param" } }, so client libraries report them like any other OpenAI error.

See also

  • ai-gateway: Get connection details and use chat models through the gateway.
  • Generate images: Generate and edit images through the gateway.
  • Generate video: Generate video from a prompt, an image, or existing media.
  • Backend functions: Write the server-side code that calls the gateway.