SoundBerry API · v1

Music generation API

Generate tracks from text, split audio into stems, split drums into percussion parts, generate an instrument stem that fits a reference mix, detect BPM and key. Same engine as the app and the VST — with your API key, every request runs on your account and credits.

Interactive reference openapi.json Create an API key

How it works

Auth — send your key as x-api-key (or Authorization: Bearer). Base URL https://soundberry.ai/api.
Synchronous — API-key requests wait for the result and return it in the same response (up to 8 minutes). No polling needed; GET /gen/status/{generationId} is there if you lose a response.
Audio in — every audio field accepts a public https:// URL (WAV/MP3) or the storage path of a previous result.
Audio out — a storage path plus a signed audioUrl valid 60 minutes. Files produced through the API are kept for 48 hours: download them.
Credits — reserved when the request starts, refunded if the generation fails. GET /gen/models shows costs, GET /user/info your balance.

Endpoints

Method	Path	What	Credits
POST	/gen/text-to-music	Generate a track from a text prompt (optionally with lyrics)	yes
POST	/gen/stem-separation	Split a mix into stems (vocals, drums, bass, other…)	yes
POST	/gen/drum-separation	Split drums into kick, snare, hi-hat, toms, cymbals…	yes
POST	/gen/stem-sample	Context-aware stem generation: an instrument part that fits a reference mix	yes
POST	/gen/beat-analysis	BPM, key and scale detection	free
POST	/gen/mix-audio	Mix several stems into one file	free
POST	/gen/beat-cut	Cut a time range out of a file	free
POST	/gen/extend-beat	Loop a file N times	free
POST	/gen/generate-lyrics	Write lyrics for a music prompt	free
GET	/gen/models	Models available to you for a capability, with credit cost	free
GET	/gen/status/{generationId}	Status and outputs of a previous generation	free
GET	/user/info	Account, credit balance, subscription	free

Full request/response schemas in the interactive reference.

Quickstart

curl -X POST https://soundberry.ai/api/gen/text-to-music \
  -H "x-api-key: sb_live_..." \
  -H "content-type: application/json" \
  -d '{"prompt": "lo-fi hip hop beat, dusty drums, warm Rhodes, 85 BPM", "model": "text-to-music-30s-v1"}'

# → { "success": true, "payload": { "audioUrl": "https://…", "audioPath": "generations/…/….wav",
#      "generationId": "…", "creditsBalance": 41.5 } }

MCP — use it from an AI agent

The same operations are exposed as MCP tools at https://soundberry.ai/api/mcp (Streamable HTTP; https://soundberry.ai/mcp works too). Authenticate with your API key as a bearer token. Works with Claude Code, Claude Desktop, Cursor and any MCP client that supports remote servers with custom headers.

Claude Code

claude mcp add --transport http soundberry https://soundberry.ai/api/mcp --header "Authorization: Bearer sb_live_..."

Codex CLI

export SOUNDBERRY_API_KEY="sb_live_..."

# ~/.codex/config.toml
[mcp_servers.soundberry]
url = "https://soundberry.ai/api/mcp"
bearer_token_env_var = "SOUNDBERRY_API_KEY"

Cursor

{
  "mcpServers": {
    "soundberry": {
      "url": "https://soundberry.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer sb_live_..."
      }
    }
  }
}

VS Code

{
  "servers": {
    "soundberry": {
      "type": "http",
      "url": "https://soundberry.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer sb_live_..."
      }
    }
  }
}

Gemini CLI

{
  "mcpServers": {
    "soundberry": {
      "httpUrl": "https://soundberry.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer sb_live_..."
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "soundberry": {
      "serverUrl": "https://soundberry.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer sb_live_..."
      }
    }
  }
}

ChatGPT connectors accept only OAuth or no-auth servers, so a bearer key cannot be used there yet.

Tool	Does
generate_music	text → track
separate_stems	mix → stems
separate_drums	drums → percussion parts
generate_stem	reference mix + prompt → one instrument part
analyze_audio	BPM / key / scale
list_models	models and credit costs per capability
get_generation	outputs of a previous generation
get_account	credits and subscription
mix_audio	stems → one mixed file
cut_audio	time range → new file
extend_audio	loop N times
generate_lyrics	music prompt → lyrics