API Reference
API Reference / Endpoints / Music

Generate songs

/v1/music/songs

Create a full song from a prompt, with optional lyrics.

POST/v1/music/songs
Auth: API keyBilling: Consumes 1 API callBehavior: AsyncScopes: audio:generate
POSTAsyncjsonaudio:generate

When to use it

Use this when you want the main text-to-song entry point for lyrical or general music generation.

Behavior on success

Returns 202 Accepted with a request_id. Poll the status endpoint or use webhooks.

Integration shape

Authorization model
audio:generate
Request format
json
Polling pattern
Poll status if the route returns processing.

Request

FieldTypeRequiredDescription
promptstringYesMusical brief, genre, mood, instrumentation, or production direction.
lyricsstringOptionalLyrics to guide the generation. Omit for more open-ended routing.

Example request

POST /v1/music/songs
const response = await fetch('https://prod-backup-backend.wubble.ai/v1/music/songs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WUBBLE_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "prompt": "Upbeat indie pop song with bright guitars and a confident chorus",
  "lyrics": "City lights are calling me home tonight"
}),
});

const payload = await response.json();
console.log(payload);

Example response

Response shapejson
{
  "success": true,
  "data": {
    "request_id": "<uuid>",
    "status": "processing",
    "estimated_seconds": 90
  }
}

Implementation notes

Returns 202 Accepted. Poll GET /v1/requests/:requestId until completed.
Use Idempotency-Key on retries to avoid duplicate jobs.

Production guidance

Pair this route with idempotency on POST requests and either request polling or webhooks whenever the response is asynchronous.
Was this page helpful?
Previous
InstrumentalsNext