Music Generation

Use POST /v1/music/plans to turn a prompt into a structured composition plan, review or adjust it, then call POST /v1/music to render the track. Ngamia returns generated audio as a binary response and meters the render against the selected catalog model's current price. ElevenLabs currently documents plan creation as having no credit cost; account rate limits and entitlements still apply.

This endpoint creates music audio. It does not create a music video, add a soundtrack to a generated video, or mix tracks together. Combining audio and video requires a separate media-processing workflow in your application.

What the Ngamia API exposes

The five public music routes cover planning and three ways to render a track. Pick the response style that fits your client:

Video-to-music uploads, saved-track editing, and inpainting are not currently exposed. Check the live catalog for enabled music models and their current pricing and parameters.

Before you generate

1. Call GET /v1/models using your API key.
2. Select an enabled model that supports music generation and review its current price and supported parameters.
3. Check the workspace balance with GET /v1/billing/balance.
4. Estimate the duration you need. Music requests are limited to 3 seconds through 10 minutes.

Music can be expensive relative to text requests. Show the estimated Ngamia credit charge and duration before the user confirms generation.

Plan before rendering

Planning lets an app show a structured composition before spending credits on the audio render:

curl --fail-with-body https://api.ngamia.cc/v1/music/plans \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Uplifting acoustic taarab instrumental with oud and hand percussion","music_length_ms":15000,"model_id":"music_v2_5"}'

The response is a standard Ngamia success envelope whose data contains ElevenLabs' composition plan. Pass that plan as composition_plan to /v1/music after review. The plan route does not generate audio or incur Ngamia credits.

Generate from a prompt

model and music_length_ms are required. Provide exactly one of prompt or composition_plan.

curl --fail-with-body https://api.ngamia.cc/v1/music \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<music-capable-model-from-the-live-catalog>",
    "prompt": "Warm instrumental for a calm Swahili-language shop announcement; acoustic guitar and soft percussion",
    "music_length_ms": 30000,
    "force_instrumental": true
  }' \
  -D generated-music.headers \
  -o generated-music.audio

The successful response body is the raw audio. Use its Content-Type response header to determine how to play or name the saved file. The response may include X-Generation-Id; retain it with your own request ID for support and usage reconciliation.

Stream a render

Use the stream route when your client can play audio incrementally. The request body uses the same fields as /v1/music; the response is audio bytes as they are produced. Save to a file for this simple command-line example:

curl --fail-with-body https://api.ngamia.cc/v1/music/stream \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<music-model-from-catalog>","prompt":"Gentle acoustic guitar and soft hand percussion","music_length_ms":15000,"force_instrumental":true}' \
  -o streamed-music.audio

For a real player, read the response body as a stream and feed chunks to an audio playback queue. Avoid buffering a long track in memory. Streaming responses are not idempotently cached; after a timeout, check the user's activity or balance before submitting another paid render.

Get audio with composition metadata

POST /v1/music/detailed accepts the same generation fields and returns a multipart/mixed response. One part contains JSON metadata (including the composition plan and song metadata); another contains the generated audio. Preserve the response Content-Type boundary and parse each part rather than treating the complete body as an audio file.

curl --fail-with-body https://api.ngamia.cc/v1/music/detailed \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<music-model-from-catalog>","prompt":"Bright instrumental with kalimba, soft bass, and a hopeful finish","music_length_ms":20000}' \
  -D detailed-music.headers \
  -o detailed-music.multipart

Use a MIME multipart parser in application code. Do not assume part order or boundary text; both are described by the response Content-Type header. This route performs a priced render.

Stream audio and metadata events

POST /v1/music/detailed/stream returns SSE events. Read the stream line by line, parse each data: payload as JSON, and handle metadata and audio chunk events as they arrive. The request schema matches /v1/music.

curl --no-buffer --fail-with-body https://api.ngamia.cc/v1/music/detailed/stream \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"model":"<music-model-from-catalog>","prompt":"A short joyful instrumental for a product launch","music_length_ms":12000,"force_instrumental":true}'

In a browser or mobile client, use an HTTP streaming reader because the request is a POST; browser EventSource only supports GET. Decode any base64 audio data in event payloads before queuing the bytes for playback. A stream may end with an error event after earlier chunks, so handle both partial audio and the final event.

Request fields

Response and errors

On success, Ngamia returns raw audio bytes rather than JSON. Check the HTTP status before saving or playing the body; errors use the documented JSON error format. Common responses include:

Use an Idempotency-Key on the non-streaming route when retrying after a timeout. The streaming route does not cache idempotent responses. Do not blindly replay a request if you do not know whether the original generation completed. Check Idempotency, Errors, and Activity & analytics for retry and usage details.

Music with speech or video

For a spoken advertisement, generate and review speech with POST /v1/audio/speech, then create background music as a separate /v1/music request. Your application can mix the two audio files with a media tool after the user approves the result. Keep speech and music as separate assets so either can be edited or regenerated without repeating the other charge.

For video, /v1/music only returns an audio track. Your application must combine the soundtrack with a video file, decide what to do with existing audio, render the finished video, and provide its own storage and download flow. Ngamia does not currently expose a single public endpoint that returns a finished music video with the generated soundtrack already attached.