Music Generation

Generate music tracks with vocals or instrumentals using AI models like Suno. Browse the full model catalog for everything currently available, or fetch the live list at any time with GET /api/v1/models?type=music_gen.

All generation endpoints accept an optional project_id body field that routes the output into a specific project. See Projects.

Endpoint

POST /api/v1/generate/music

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	Description of the music (e.g., "upbeat pop song about summer")
`model`	string	No	Model identifier from `GET /api/v1/models?type=music` (default: server-selected)
`style`	string	No	Music style (e.g., `"pop"`, `"rock"`, `"electronic"`, `"jazz"`)
`instrumental`	boolean	No	Instrumental only, no vocals (default: `false`)
`lyrics`	string	No	Custom lyrics for the song
`vocal_gender`	string	No	`"m"` or `"f"` for vocal gender preference
`enhance_prompt`	boolean	No	Enhance the prompt (default: `true`)
`duration_seconds`	number	No	Exact track length in seconds for length-controllable models (e.g. ElevenLabs Music, `music-v1`). Clamped to 5–300. Without it those models default to a ~10s track. Suno models ignore this field (Suno decides its own length).

Model identifiers are Kolbo-specific — always fetch available models from GET /api/v1/models?type=music first. Omitting model uses the server default, which is recommended for most use cases.

Examples

Simple (Recommended)

Omit model to use the server default — the simplest way to get started:

curl -X POST https://api.kolbo.ai/api/v1/generate/music \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Relaxing lo-fi hip hop beat for studying"}'

With Specific Model

To choose a specific model, first fetch identifiers from GET /api/v1/models?type=music, then pass the identifier value (e.g., suno-v5, elevenlabs-music-v1):

curl -X POST https://api.kolbo.ai/api/v1/generate/music \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Relaxing lo-fi hip hop beat for studying",
    "model": "suno-v5"
  }'

With Style and Lyrics

curl -X POST https://api.kolbo.ai/api/v1/generate/music \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Emotional ballad",
    "style": "pop",
    "lyrics": "Walking through the rain\nThinking of you again",
    "vocal_gender": "f"
  }'

Instrumental

curl -X POST https://api.kolbo.ai/api/v1/generate/music \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Epic orchestral trailer music",
    "instrumental": true,
    "style": "cinematic"
  }'

Response

Generation Started

{
  "success": true,
  "generation_id": "mus_abc123",
  "type": "music",
  "model": "suno-v5",
  "credits_charged": 15,
  "poll_url": "/api/v1/generate/mus_abc123/status",
  "poll_interval_hint": 8
}

Completed Status

{
  "success": true,
  "generation_id": "mus_abc123",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://cdn.kolbo.ai/audio/..."],
    "model": "suno-v5",
    "title": "Summer Vibes",
    "duration": 120,
    "lyrics": "Generated or provided lyrics..."
  }
}

JavaScript Example

const KOLBO_API_KEY = "kolbo_live_..."; // Replace with your API key
const BASE_URL = "https://api.kolbo.ai/api";

async function generateMusic() {
  const response = await fetch(`${BASE_URL}/v1/generate/music`, {
    method: "POST",
    headers: {
      "X-API-Key": KOLBO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Upbeat pop song about summer adventures",
      style: "pop",
      instrumental: false,
    }),
  });

  const data = await response.json();
  if (!data.success) throw new Error(data.error);

  const generationId = data.generation_id;
  const pollUrl = data.poll_url;

  // Poll for result
  while (true) {
    await new Promise((r) => setTimeout(r, 8000));
    const statusRes = await fetch(`${BASE_URL}${pollUrl}`, {
      headers: { "X-API-Key": KOLBO_API_KEY },
    });
    const status = await statusRes.json();

    if (status.state === "completed") {
      console.log("Music URLs:", status.result.urls);
      return status.result;
    }
    if (status.state === "failed") {
      throw new Error(status.error || "Generation failed");
    }
    console.log(`Progress: ${status.progress}%`);
  }
}

generateMusic().catch(console.error);

Python Example

import requests
import time

KOLBO_API_KEY = "kolbo_live_..."  # Replace with your API key
BASE_URL = "https://api.kolbo.ai/api"

response = requests.post(
    f"{BASE_URL}/v1/generate/music",
    headers={"X-API-Key": KOLBO_API_KEY},
    json={
        "prompt": "Cinematic orchestral theme",
        "instrumental": True,
        "style": "cinematic",
    },
)
data = response.json()
if not data.get("success"):
    raise Exception(data.get("error", "Request failed"))

poll_url = data["poll_url"]

while True:
    time.sleep(8)
    status = requests.get(
        f"{BASE_URL}{poll_url}",
        headers={"X-API-Key": KOLBO_API_KEY},
    ).json()

    if status["state"] == "completed":
        print("URLs:", status["result"]["urls"])
        break
    if status["state"] == "failed":
        raise Exception(status.get("error", "Generation failed"))
    print(f"Progress: {status.get('progress', 0)}%")

Tips

Music generation typically takes 30 seconds to 2 minutes
Suno generates two track variations per request
Use descriptive prompts for better results: include genre, mood, tempo, and instruments
Need an exact track length (e.g. a 30s jingle or a 2-minute bed)? Pass duration_seconds with a length-controllable model like ElevenLabs Music (music-v1) — without it those models default to ~10 seconds

On this page