Music routes
GET /api/music/models
Fetch the signed-in account’s model catalog from Ngamia GET /v1/models. Requires an allowed origin and a valid Ngamia session. Uses a 15-second upstream timeout with one refresh-and-retry after a 401.
curl 'http://localhost:4175/api/music/models' \
-H 'Origin: http://localhost:4174' \
--cookie 'ngamia_music_access=REDACTED; ngamia_music_refresh=REDACTED'The body and content type are passed through with the upstream status. The Studio selects a returned model that advertises music modality/capability or has “music” in its identity. Do not hardcode a model ID or price; catalog content can change.
POST /api/music/generate
Generate one track and stream the returned audio bytes. Requires an allowed origin and a session cookie. The request requires valid JSON and is posted to Ngamia POST /v1/music.
{
"model": "model-id-from-live-catalog",
"prompt": "Bongo Flava: A hopeful night drive through Dar es Salaam, warm piano and a memorable Swahili chorus.",
"music_length_ms": 90000,
"force_instrumental": false,
"is_public": false
}| Field | Type | Required | Rules |
|---|---|---|---|
model | string | Yes | Trimmed; 1–120 characters; should come from live catalog |
prompt | string | Yes | Trimmed; 1–4,100 characters |
music_length_ms | integer | Yes | 3,000 through 600,000 milliseconds inclusive |
force_instrumental | boolean | No | Only literal true is forwarded as true; all else false |
is_public | boolean | No | Only literal true is forwarded as true; all else false |
The upstream payload contains exactly these five keys. Other input properties are ignored. An optional request Idempotency-Key is forwarded as Idempotency-Key. The Studio sends a UUID per generation action. The shared request helper refreshes and retries once if Ngamia responds 401 and a refresh cookie is available.
Success is 200 with streamed bytes. The content type uses the upstream value or defaults to audio/mpeg; Cache-Control: no-store is set. The API forwards Content-Disposition, X-Generation-Id, and X-Music-Creation-Id if present. Read the response as a Blob, not JSON.
| Failure | Status and behavior |
|---|---|
| Origin rejected | 403 JSON |
| No session cookies or helper returns no response | 401 JSON |
| Invalid JSON | 400 JSON |
| Prompt/model/duration invalid | 400 JSON |
| Ngamia non-2xx | Same status, JSON error with extracted upstream message when possible |
| Upstream timeout | 502 JSON; check account activity before retry |
| Other thrown fetch failure | 502 JSON |
Duration conversion: music_length_ms = durationSeconds * 1000. The web UI’s default 30-second choice therefore sends 30000. Content exposure headers allow the browser to read generation and creation identifiers across origins.
See Generate a track for a complete activity diagram and browser example.