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.

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).