API reference

Generate songs from lyrics and a style with the YuE2 model. Authenticate with an API key from the studio (Authorization: Bearer ws_...).

Base URL https://studio.weavyaudio.com/api/v1 · OpenAPI 3.1: /api/v1/openapi.json · Quickstart: API quickstart

Authentication

Create a key in the studio (API keys) and send it on every request: Authorization: Bearer ws_…. Keys can be revoked at any time.

Endpoints

POST/generations

Create a song (one or more takes). Queues one render per take on separate GPUs. Returns immediately; poll each id until its status is done.

Request body

Field	Type	Default · range	Description
`title`required	`string`	length 1–120	Song title.
`artist`	`string`	length 0–120	Artist / act name (label only).
`language`	`string`	length 0–40	Vocal language, e.g. "English" or "Polish". Put first in the style.
`style`required	`string`	length 3–1000	Genre, instruments, voice, mood, BPM, key - comma separated.
`lyrics`required	`string`	length 1–6000	Lyrics with section tags: [Verse], [Chorus], [Bridge]...
`cot`	`"full" \| "melody" \| "off"`	`"full"`	full = write a melody-and-chord score first (most stable); melody = melody only; off = direct.
`cfg_scale`	`number`	`2` 1–4	Style strength (classifier-free guidance). 1 = off.
`takes`	`integer`	`2` 1–8	How many versions to render (each on its own GPU slot).
`seed`	`integer`	0–2147483647	Fixed seed for the first take; omitted = random.
`lock_seed`	`boolean`	`false`	Use the same seed for every take (only settings differ).
`max_len_s`	`integer`	`300` 30–360	Upper bound for the song length in seconds.
`abc`	`string`	length 0–20000	Optional ABC score (melody + chords) to sing instead of planning one.
`abc_sampling`	`object`		Sampling for the score stage.
`semantic_sampling`	`object`		Sampling for the audio-token stage.

Responses

201 Queued.
401 Missing or invalid API key.
422 Validation error.
429 Hourly limit reached.

curl -X POST https://studio.weavyaudio.com/api/v1/generations \
  -H "Authorization: Bearer $WEAVY_KEY" -H "Content-Type: application/json" \
  -d '{"title":"City Lights","language":"English","style":"warm piano pop, expressive female voice, 88 BPM","lyrics":"[Verse]\nNeon fades along the lane\n\n[Chorus]\nLet the day come into view","takes":2,"cfg_scale":2}'

GET/generations

List generations. Newest first. To page, pass before = created_at of the last item.

Parameter	In	Type	Description
`limit`	query	`integer` 1–200
`before`	query	`integer`	Unix ms cursor.

Responses

200 A page of generations.
401 Missing or invalid API key.

curl https://studio.weavyaudio.com/api/v1/generations?limit=20 -H "Authorization: Bearer $WEAVY_KEY"

GET/generations/{id}

Get one generation.

Parameter	In	Type	Description
`id`	path	`string`	Generation id.

Responses

200 The generation.
401 Unauthorized.
404 Not found.

curl https://studio.weavyaudio.com/api/v1/generations/GEN_ID -H "Authorization: Bearer $WEAVY_KEY"

DELETE/generations/{id}

Delete a generation and its files. Cancels it first if it is still running.

Parameter	In	Type	Description
`id`	path	`string`	Generation id.

Responses

204 Deleted.
401 Unauthorized.
404 Not found.

curl -X DELETE https://studio.weavyaudio.com/api/v1/generations/GEN_ID -H "Authorization: Bearer $WEAVY_KEY"

POST/generations/{id}/cancel

Cancel a queued or running generation.

Parameter	In	Type	Description
`id`	path	`string`	Generation id.

Responses

200 The generation.
401 Unauthorized.
404 Not found.

curl -X POST https://studio.weavyaudio.com/api/v1/generations/GEN_ID/cancel -H "Authorization: Bearer $WEAVY_KEY"

The Generation object

Field	Type	Default · range	Description
`id`required	`string`		Generation id (one per take).
`batch_id`required	`string`		Shared by all takes created in one request.
`status`required	`"queued" \| "running" \| "done" \| "failed" \| "cancelled"`
`stage`required	`"planning" \| "generating" \| "encoding" \| "uploading" \| null`		Current stage while running.
`title`required	`string`
`artist`required	`string \| null`
`language`required	`string \| null`
`style`required	`string`
`cot`required	`"full" \| "melody" \| "off"`
`cfg_scale`required	`number`
`seed`required	`integer`	-9007199254740991–9007199254740991
`max_len_s`required	`integer`	-9007199254740991–9007199254740991
`abc_sampling`required	`object \| null`
`semantic_sampling`required	`object \| null`
`progress`required	`object \| null`
`error`required	`string \| null`
`duration_s`required	`number \| null`		Song length in seconds (done only).
`render_s`required	`number \| null`		GPU time in seconds (done only).
`audio`required	`object \| null`		Absolute download URLs (done only).
`lyrics`	`string`
`abc_in`	`string \| null`
`abc_out`	`string \| null`		The ABC score the model sang.
`created_at`required	`integer`	-9007199254740991–9007199254740991	Unix ms.
`finished_at`required	`integer \| null`

The Sampling object

Field	Type	Default · range	Description
`temperature`	`number`	0–2	Randomness. 0 = greedy.
`top_p`	`number`	0.1–1	Nucleus sampling cut-off.
`top_k`	`integer`	1–500	Only the k most likely tokens are considered.
`repetition_penalty`	`number`	1–3	Penalty for tokens repeated inside the window.
`penalty_window`	`integer`	1–1000	How many recent tokens the penalty looks at.

Errors and limits

Errors are JSON {"error": "...", "issues": [...]}. Codes: 401 bad or missing key · 404 not found · 422 validation (see issues) · 429 more than 40 takes in the last hour.