Generate a track

Activity diagram

Browser example

const api = (path, init = {}) => fetch(`${API_BASE}${path}`, {
  ...init,
  credentials: 'include',
  cache: 'no-store'
});
 
const catalogResponse = await api('/api/music/models');
if (!catalogResponse.ok) throw new Error('Could not load models');
const catalog = await catalogResponse.json();
const model = (catalog.data ?? catalog).find((item) => item.model === selectedModelId);
if (!model) throw new Error('Select a current model from the catalog');
 
const response = await api('/api/music/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    model: model.model,
    prompt: 'Afro-soul: ...',
    music_length_ms: 90000,
    force_instrumental: false,
    is_public: false
  })
});
if (!response.ok) {
  const error = await response.json().catch(() => null);
  throw new Error(error?.error?.message ?? `Generation failed (${response.status})`);
}
const audioBlob = await response.blob();
const playbackUrl = URL.createObjectURL(audioBlob);

Revoke the object URL with URL.revokeObjectURL(playbackUrl) when the player no longer needs it. The response may include X-Music-Creation-Id; after a successful creation, the production Studio reloads /api/ngamia/v1/music/creations, account balance, and activity summaries through the proxy.

Request constraints

Prompt length is 1 to 4,100 characters after trimming. Model identifier is 1 to 120 characters. Duration must be an integer number of milliseconds from 3 seconds to 10 minutes. The user interface calculates credits from the live catalog when a model exposes a per-1,000-credit input price; the server route itself does not estimate price or enforce a balance check before forwarding.

Retry safely

The web app sends a UUID idempotency key on each deliberate submit. If the call times out, the generation may still have completed upstream. Check the account’s creation list or activity first. A retry of the same logical operation should reuse its idempotency key if the upstream contract honors keys; a newly requested track should use a new one. This API does not itself guarantee deduplication.