docs / resources / api-reference

API reference

The whole surface at a glance. Base URL https://api.songapi.dev; every /v1 route takes Authorization: Bearer sk_live_… or sk_test_… (see authentication). Submissions return 202 with a generation object; results arrive by polling or webhook.

## Endpoints

ENDPOINT	CREDITS	WHAT IT DOES
`POST /v1/generate`	11	Full song from a prompt or custom lyrics
`POST /v1/extend`	11	Lengthen an existing track from a timestamp
`POST /v1/cover`	11	Restyle an existing track into a new genre
`POST /v1/add-vocals`	11	Add sung vocals to an instrumental
`POST /v1/lyrics`	1	Generate lyrics, no audio
`GET /v1/generations/:id`	—	Fetch one generation (polling)
`GET /v1/generations`	—	List generations (limit, offset, status)

Credits are charged on submission and refunded automatically if the job fails. Sandbox keys are never charged. One credit is $0.005 at the base rate — packs from $5.

## Models

Every music endpoint accepts an optional model: v3.5, v4, v4.5, v4.5-plus, v4.5-all, v5 (default), v5.5. Newer models generally produce higher-fidelity audio; all cost the same 11 credits.

## The generation object

FIELD	TYPE	DESCRIPTION
`id`	string	Generation id, prefixed gen_.
`object`	string	Always "generation".
`env`	string	"live" or "sandbox".
`type`	string	"generate", "extend", "cover", "add_vocals", or "lyrics".
`status`	string	"queued" → "processing" → "complete" \| "failed".
`prompt`	string	The prompt (or lyrics/style) the job was submitted with.
`model`	string \| null	Model used, e.g. "v5". null for lyrics jobs.
`credits`	number	Credits charged (refunded if the job fails).
`clips`	Clip[] \| null	Output variations — two for music jobs, one for lyrics. null until complete.
`error`	string \| null	Failure reason when status is "failed".
`duration_secs`	number \| null	Duration of the first clip, in seconds.
`audio_url`	string \| null	Audio URL of the first clip.
`created_at`	string	ISO 8601 submission time.
`completed_at`	string \| null	ISO 8601 completion time.

## The clip object

Each entry of clips is one output variation:

FIELD	TYPE	DESCRIPTION
`id`	string	Clip id, prefixed clip_.
`audio_url`	string \| null	Rendered audio for this variation.
`image_url`	string \| null	Cover art, when available.
`duration_secs`	number \| null	Clip length in seconds.
`lyrics`	string \| null	Lyrics sung in this clip (or generated lyrics).
`tags`	string \| null	Style tags the model applied.
`title`	string \| null	Generated track title.

## Errors & limits

Error responses are { "error": "code", "message": "…" } — codes and validation details in errors. Rate limit: 300 requests/minute per key; generation concurrency: 2 in-flight by default (30 / 60 on higher tiers) with overflow queued, never rejected — see rate limits.