Music Generation

POST /api/v1/generate/music

curl -X POST https://api.kolbo.ai/api/v1/generate/music \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/clip.mp4",
    "prompt": "tense, driving percussion under the chase",
    "num_samples": 2,
    "duration_seconds": 30
  }'

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"}'

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.5"
  }'

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"
  }'

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"
  }'

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "music",
  "model": "suno-v5.5",
  "credits_charged": null,
  "poll_url": "/v1/generate/68f2c1a9b4e5d6f7a8b9c0d1/status",
  "poll_interval_hint": 8,
  "session_id": "68f2c1a9b4e5d6f7a8b9c0d2",
  "project_id": "68f2c1a9b4e5d6f7a8b9c0d3"
}

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "music",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": [
      "https://media.kolbo.ai/music/.../track-1.mp3",
      "https://media.kolbo.ai/music/.../track-2.mp3"
    ],
    "tracks": [
      { "title": "Summer Vibes", "duration": 187.2, "thumbnail_url": null, "model": "suno-v5.5" },
      { "title": "Summer Vibes", "duration": 191.0, "thumbnail_url": null, "model": "suno-v5.5" }
    ],
    "title": "Summer Vibes",
    "duration": 187.2,
    "duration_seconds": 180,
    "lyrics": "[Verse 1]\n...",
    "prompt_used": "Relaxing lo-fi hip hop beat for studying",
    "model": "suno-v5.5",
    "created_at": "2026-07-20T14:20:00Z"
  },
  "credits_used": 24,
  "credits_breakdown": [
    { "model": "suno-v5.5", "amount": 24, "base": 20, "final": 24, "duration_multiplier": 1, "pricing": null }
  ]
}

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 started = await response.json();
  if (!started.success) throw new Error(started.error);

  // Minimal loop. A production client should also handle transient HTTP errors and
  // an overall timeout — see /docs/developer-api/polling-and-cancellation.
  while (true) {
    await new Promise((r) => setTimeout(r, started.poll_interval_hint * 1000));
    const status = await fetch(
      `${BASE_URL}/v1/generate/${started.generation_id}/status`,
      { headers: { "X-API-Key": KOLBO_API_KEY } }
    ).then((r) => r.json());

    // Music only: "completed" at progress 70 means temporary streaming URLs.
    // Keep polling until progress is 100 for the permanent CDN files.
    if (status.state === "completed" && status.progress === 100) {
      console.log("Music URLs:", status.result.urls); // usually two tracks
      return status.result;
    }
    if (status.state === "failed") throw new Error(status.error || "Generation failed");
    if (status.state === "cancelled") throw new Error("Generation was cancelled");
  }
}

generateMusic().catch(console.error);

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",
    },
)
started = response.json()
if not started.get("success"):
    raise Exception(started.get("error", "Request failed"))

# Minimal loop. Add transient-error retries and an overall timeout for production
# — see /docs/developer-api/polling-and-cancellation.
while True:
    time.sleep(started["poll_interval_hint"])
    status = requests.get(
        f"{BASE_URL}/v1/generate/{started['generation_id']}/status",
        headers={"X-API-Key": KOLBO_API_KEY},
    ).json()

    # Music only: "completed" at progress 70 means temporary streaming URLs.
    # Keep polling until progress is 100 for the permanent CDN files.
    if status["state"] == "completed" and status["progress"] == 100:
        print("URLs:", status["result"]["urls"])  # usually two tracks
        break
    if status["state"] == "failed":
        raise Exception(status.get("error", "Generation failed"))
    if status["state"] == "cancelled":
        raise Exception("Generation was cancelled")