API reference

Generate songs from lyrics and a style with YuE2, HeartMuLa or ACE-Step; cover, extend, repaint and re-arrange existing audio; split stems; write lyrics. 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
`engine`	`"yue2" \| "heartmula" \| "ace"`	`"yue2"`	Model: yue2 (CC BY-NC), heartmula (Apache 2.0) or ace (MIT).
`task`	`"create" \| "cover" \| "reference" \| "extend" \| "repaint" \| "accompany"`	`"create"`	create a new song, or work from `source`: cover, reference (ace), extend (ace), repaint (ace), accompany (ace).
`source`	`object`		Source audio for every task except create.
`edit`	`object`		Options for extend / repaint / accompany / covers.
`heart`	`object`		HeartMuLa-only options.
`ace`	`object`		ACE-Step-only options.
`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), YuE2 and HeartMuLa. 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}/stems

Split a finished take into stems. Vocals, drums, bass, guitar, piano, other. Runs in the background; read the take again for its `stems` field.

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

Responses

202 Started.
401 Unauthorized.
409 Not finished, or already splitting.
503 Stem service not configured.

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

POST/uploads

Upload an audio file (max 60 MB).

Request body · `multipart/form-data`

Field	Type	Default · range	Description
`file`required	`string`

Responses

201 Stored (converted to MP3 320k).
401 Unauthorized.
413 Too large.
415 Not audio.
422 Undecodable.

curl -X POST https://studio.weavyaudio.com/api/v1/uploads -H "Authorization: Bearer $WEAVY_KEY" -F file=@demo.mp3

GET/uploads

List your uploads.

Responses

200 Newest first.
401 Unauthorized.

GET/voices

List ACE-Step voices.

Responses

200 All voices; only status "ready" can be used.
401 Unauthorized.

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

POST/lyrics

Write or rewrite lyrics with Claude. 30 drafts per hour. Returns lyrics with section tags, ready for any engine.

Request body

Field	Type	Default · range	Description
`idea`	`string`	length 0–1000	What the song is about.
`language`	`string`	length 0–40
`style`	`string`	length 0–1000
`artist`	`string`	length 0–120
`current`	`string`	length 0–6000	Existing lyrics (mode rewrite).
`mode`	`"new" \| "rewrite"`

Responses

200 Draft.
401 Unauthorized.
429 Hourly limit reached.
502 Writer failed.

curl -X POST https://studio.weavyaudio.com/api/v1/lyrics -H "Authorization: Bearer $WEAVY_KEY" -H "Content-Type: application/json" \
  -d '{"idea":"a night drive after a breakup","language":"Polish","style":"synthwave, male vocal"}'

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"`
`engine`required	`"yue2" \| "heartmula" \| "ace"`
`task`required	`"create" \| "cover" \| "reference" \| "extend" \| "repaint" \| "accompany"`		What the take was made with: a new song or work on a source.
`source_ref`required	`object \| null`		The source audio, if any.
`stems`required	`object \| null`		Separated stems after POST /generations/{id}/stems.
`stage`required	`"transcribing" \| "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 Voice object

Field	Type	Description
`id`required	`string`	Use as ace.voice.
`name`required	`string`
`artist`required	`string \| null`
`status`required	`"training" \| "ready" \| "failed"`
`error`required	`string \| null`
`has_lora`required	`boolean`
`reference`required	`boolean`

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.

API reference

Authentication

Endpoints

POST/generations

Request body

Responses

GET/generations

Responses

GET/generations/{id}

Responses

DELETE/generations/{id}

Responses

POST/generations/{id}/stems

Responses

POST/uploads

Request body · multipart/form-data

Responses

GET/uploads

Responses

GET/voices

Responses

POST/lyrics

Request body

Responses

POST/generations/{id}/cancel

Responses

The Generation object

The Voice object

The Sampling object

Errors and limits

Request body · `multipart/form-data`