Music Generation

Generate music tracks with vocals or instrumentals using AI models like Suno.

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

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

On this page