POST /v1/generate — SongAPI Docs

docs / endpoints / generate

POST/v1/generate

Create a full song — vocals, instruments, and all — from a text prompt, or from your own lyrics in custom mode. Returns 202 Accepted immediately; the track renders in the background.

$Billing: 11 credits per generation — two variations (clips) included. Sandbox keys generate silent placeholder tracks for free.

## Request body

promptstringDescription of the song: genre, mood, subject, structure. Up to 3,000 characters. Required unless lyrics is set.

lyricsstringYour own lyrics (custom mode), up to 5,000 characters. Provide prompt or lyrics — at least one is required.

stylestringMusical style tags, e.g. "indie pop, upbeat, female vocals". Up to 1,000 characters.

titlestringTrack title, up to 100 characters.

negative_tagsstringStyles to avoid, up to 500 characters.

instrumentalbooleanGenerate without vocals. Default: false.

vocal_gender"m" | "f"Preferred vocal gender.

style_weightnumberHow strongly to follow style, 0–1.

weirdnessnumberHow experimental the result should be, 0–1.

modelstringGeneration model: v3.5, v4, v4.5, v4.5-plus, v4.5-all, v5 (default), or v5.5.

webhook_urlstringHTTPS URL to POST the completed generation to — skips polling. See webhooks.

## Example request

curl https://api.songapi.dev/v1/generate \
  -H "Authorization: Bearer $SONGAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "upbeat indie pop song about summer road trips",
    "model": "v5",
    "instrumental": false
  }'

const res = await fetch("https://api.songapi.dev/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SONGAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "upbeat indie pop song about summer road trips",
    model: "v5",
    instrumental: false
  })
});
const { id } = await res.json();

import os, requests

res = requests.post(
    "https://api.songapi.dev/v1/generate",
    headers={"Authorization": f"Bearer {os.environ['SONGAPI_KEY']}"},
    json={
        "prompt": "upbeat indie pop song about summer road trips",
        "model": "v5",
        "instrumental": False,
    },
)
gen_id = res.json()["id"]

## Response · 202 Accepted

202 Acceptedjson

{
  "id": "gen_h2vJk8PqXw4RtY7NcAbD",
  "object": "generation",
  "env": "live",
  "type": "generate",
  "status": "queued",
  "prompt": "upbeat indie pop song about summer road trips",
  "model": "v5",
  "credits": 11,
  "clips": null,
  "error": null,
  "duration_secs": null,
  "audio_url": null,
  "created_at": "2026-07-22T03:47:00.000Z",
  "completed_at": null
}

Poll GET /v1/generations/:id until status is "complete", or set webhook_url to be notified. Completed generations include a top-level audio_url and duration_secs, plus a clips array with both variations — each with its own audio_url, lyrics, title, and tags. See the generation object for every field.