API quickstart

Everything the studio does is available over a small REST API. Full reference: API reference · machine-readable: openapi.json.

1. Get a key

In the studio open API keys and create one. It starts with ws_ and is shown once – store it safely. Send it as a bearer token.

2. Create a song

curl -X POST https://studio.weavyaudio.com/api/v1/generations \
  -H "Authorization: Bearer ws_YOUR_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
  }'

The response lists one object per take with status: "queued".

3. Wait for it

Poll GET /api/v1/generations/{id} every 5–10 s. status goes queued → running → done (or failed / cancelled); while running, stage and progress tell you where it is.

4. Download

When status is done, audio.flac and audio.mp3 hold absolute URLs.

5. Work from audio

Upload a file, then use it as a source with a task:

curl -X POST https://studio.weavyaudio.com/api/v1/uploads -H "Authorization: Bearer ws_YOUR_KEY" -F file=@demo.mp3
# -> {"data": {"id": "UPLOAD_ID", "duration_s": 182.4, ...}}

curl -X POST https://studio.weavyaudio.com/api/v1/generations \
  -H "Authorization: Bearer ws_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"engine": "ace", "task": "extend", "source": {"kind": "upload", "id": "UPLOAD_ID"},
       "edit": {"extend_s": 30}, "title": "Demo (extended)", "style": "indie rock, male vocal",
       "lyrics": "[Verse]\n...whole song...\n\n[Outro]\nnew closing lines", "takes": 1}'

Tasks: create (default), cover (any engine), reference, extend, repaint (edit.start_s / edit.end_s), accompany (edit.instruments) – see Covers, extend, repaint. A take as the source: {"kind": "generation", "id": "...", "stem": "vocals"}.

Also: POST /api/v1/generations/{id}/stems (split a take; the result appears in its stems field), GET /api/v1/voices (voice ids for ace.voice), POST /api/v1/lyrics ({"idea", "language", "style"} → {"title", "lyrics"}).

Limits and errors

• 40 takes per hour per account; up to 8 takes per request.
• Errors are JSON: {"error": "...", "issues": [...]} with 401 (bad key), 404, 422 (validation) or 429 (limit).