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

Related music routes on this page: /generate/music/composition-plan, /generate/music/reference-audio and /generate/music/edit-section for ElevenLabs Music v2.5 structured songs, and /generate/music/extend, /generate/music/cover and /generate/music/import for working from existing audio.

Request Body

Suno fine-controls (optional)

Advanced controls honored by Suno models; ignored by others. Most reach the provider only in custom mode — see the callout below.

Score an Existing Video

Supplying video_url routes the request through the Vision Music pipeline instead of the regular text-to-music flow. prompt becomes optional in this mode (it is forwarded as free-form guidance). The result is still an audio track — this endpoint always produces a music file, never a video muxed with the score.

Which pipeline runs depends on the model's requires_video_input flag in GET /api/v1/models?type=music_gen:

• requires_video_input: true (today sonilo/v1.1/video-to-music) — the model scores the clip natively. keep_speech_vocal, num_samples, start_offset and duration_seconds apply. The URL must resolve to a video, otherwise the generation fails with This model requires a video upload.
• any other music model (including the default suno-v6 when you omit model) — the media is analysed first (prompt, style and lyrics are derived from it), then normal music generation runs. The four fields above are ignored on this path.

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",
    "model": "sonilo/v1.1/video-to-music",
    "prompt": "tense, driving percussion under the chase",
    "start_offset": 0,
    "duration_seconds": 30
  }'

Structured Songs (ElevenLabs Music v2.5)

Instead of a prompt, you can send ElevenLabs Music v2.5 an explicit composition plan: an ordered list of chunks, each one either a section to generate or a slice of an existing song to keep unchanged. Pass it as composition_plan on POST /api/v1/generate/music. The request always runs on music-v1 (your model is ignored), and every Suno-oriented field is ignored — only composition_plan, seed, title, project_id and session_id are read. The response and polling are the same as any music generation.

composition_plan must be an object with a chunks array — { "chunks": [ ... ] }. A bare array returns 400 MISSING_PLAN.

A plan holds 1–30 chunks (400 MISSING_PLAN / 400 TOO_MANY_CHUNKS); a chunk that is not an object returns 400 INVALID_CHUNK. Chunks are forwarded to ElevenLabs as written, so other ElevenLabs chunk fields pass through unvalidated. A song_id comes from result.song_id of an earlier ElevenLabs Music v2.5 generation, or from reference audio you uploaded.

Pricing: the total plan length (generated duration_ms plus kept range lengths) is billed per started minute at the music-v1 catalog rate. The credits are held when the job starts and released if it fails.

curl -X POST https://api.kolbo.ai/api/v1/generate/music \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Night Drive",
    "seed": 42,
    "composition_plan": {
      "chunks": [
        { "text": "[Intro]", "duration_ms": 8000, "positive_styles": ["synthwave", "warm analog pads"] },
        { "text": "[Verse]\nCity lights in the rear view", "duration_ms": 30000, "positive_styles": ["female vocals"] },
        { "text": "[Chorus]\nWe drive until the morning", "duration_ms": 25000, "positive_styles": ["anthemic"], "context_adherence": "high" }
      ]
    }
  }'

Get a starter plan

POST /api/v1/generate/music/composition-plan

Free — creates no generation, charges no credits and is not counted in the generation rate-limit bucket. ElevenLabs drafts a plan from a plain-text prompt for you to edit and submit as composition_plan.

The response is passed through from the music service unwrapped — it uses status, not success:

{ "status": true, "plan": { "chunks": [ { "text": "[Intro]", "duration_ms": 8000, "positive_styles": ["..."], "negative_styles": [] } ] } }

A provider failure returns { "status": false, "message": "...", "code": "COMPOSITION_PLAN_FAILED" } with HTTP 422 or 500.

Reference audio

POST /api/v1/generate/music/reference-audio

Uploads an audio file from your media library to ElevenLabs and returns a song_id you can use in a conditioning_ref or a kept chunk. Billed like generating a track of the clip's length — per started minute at the music-v1 rate, measured from the file. ElevenLabs bills the upload itself, so this is charged even if the clip is later rejected for copyright.

The file must be on Kolbo storage (400 UNTRUSTED_MEDIA_URL) and at most 50 MB. Errors: 404 MEDIA_NOT_FOUND (not yours, not audio, or missing), 400 UNREADABLE_AUDIO (length could not be measured), 403 INSUFFICIENT_CREDITS, 503 MEDIA_PROCESSING_BUSY (retry after the Retry-After header), 422/500 REFERENCE_UPLOAD_FAILED. Like the plan route, the response is unwrapped and camelCase:

{ "status": true, "songId": "...", "durationSeconds": 42.6, "maxConditioningMs": 30000, "creditsCharged": 40 }

Edit a section

POST /api/v1/generate/music/edit-section

Regenerates one time range of an existing ElevenLabs Music v2.5 track and keeps the rest unchanged. The server builds a keep / regenerate / keep plan from the source track and creates a new generation; the source is untouched. Billed like a composition_plan of the full track length.

Missing source_generation_id, start_ms or end_ms returns 400 MISSING_EDIT_PARAMS. A source not found in the session returns 404 SOURCE_NOT_FOUND; a track with no stored song reference (anything not made with ElevenLabs Music v2.5) returns 400 NOT_EDITABLE. The response is the standard Generation Started shape with model: "music-v1" — poll the new generation_id.

Extend or Cover Existing Audio

Two Suno operations work on audio you already have:

• Extend — POST /api/v1/generate/music/extend continues a track from a point in the source. The source is auto-trimmed to 8 minutes.
• Cover — POST /api/v1/generate/music/cover re-records a track in a new style. The source is auto-trimmed to 2 minutes.

If the source cannot be trimmed, the request fails with 400 AUDIO_TRIM_FAILED. There is no length control on either route — duration_seconds is not read. Both always run in Suno custom mode: without lyrics and with instrumental off, lyrics are transcribed from the source or written from your prompt, and a style is generated when you omit one.

*Send audio_url (with rights_confirmed: true) or upload_id; neither returns 400 AUDIO_SOURCE_REQUIRED.

The response is the standard Generation Started shape, and the result is read the same way (Suno returns two tracks). These routes hold the connection open while the source downloads and converts, so allow a generous client timeout.

curl -X POST https://api.kolbo.ai/api/v1/generate/music/cover \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/my-song.mp3",
    "rights_confirmed": true,
    "model": "suno-v6",
    "style": "acoustic folk, fingerpicked guitar",
    "prompt": "intimate acoustic version"
  }'

Import once, reuse many times

POST /api/v1/generate/music/import

Downloads and converts a public audio URL once and returns an upload_id to pass to extend or cover. Free — no credits, no generation.

{
  "success": true,
  "upload_id": "68f2c1a9b4e5d6f7a8b9c0e1",
  "upload_type": "cover",
  "audio_url": "https://...",
  "duration": 184.2,
  "file_size": 4420311,
  "format": "mp3",
  "session_id": "68f2c1a9b4e5d6f7a8b9c0d2",
  "project_id": "68f2c1a9b4e5d6f7a8b9c0d3"
}

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_gen, then pass the identifier value:

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

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

This endpoint is asynchronous and fire-and-forget: the POST returns as soon as the job is queued and never contains audio.

Generation Started

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

Completed Status

GET /api/v1/generate/{generation_id}/status

{
  "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-v6" },
      { "title": "Summer Vibes", "duration": 191.0, "thumbnail_url": null, "model": "suno-v6" }
    ],
    "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-v6",
    "created_at": "2026-07-20T14:20:00Z"
  },
  "credits_used": 24,
  "credits_breakdown": [
    { "model": "suno-v6", "amount": 24, "base": 20, "final": 24, "duration_multiplier": 1, "pricing": null }
  ]
}

The output lives in result.urls — an array of strings. Suno normally returns two variations per request, so do not assume a single track. result.tracks is index-aligned with urls and carries title, duration (seconds), thumbnail_url and model per track.

result.duration_seconds is the length you asked for (null when you sent none); result.duration is the length actually delivered. They routinely differ — asking for 45 delivered 47.32 — and result.tracks[].duration carries the real length of each returned track.

result (and credits_used / credits_breakdown) appear only under a completed state. tracks[].thumbnail_url carries the track's cover art when the provider returned one (Suno does), otherwise null. ElevenLabs Music v2.5 results also carry result.song_id — reuse it in a later composition_plan, or edit a section of that generation.

Failure and cancellation

A failed generation is still an HTTP 200 with success: true — the failure is in state, with an error string carrying the provider message. cancelled carries neither result nor error, so treat all three terminal states explicitly. Music credits are deducted only after a track is delivered, so a failed generation costs nothing and POST /v1/generate/{id}/cancel reports credits_refunded: 0. See Polling & Cancellation.

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

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",
    },
)
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")

Tips

• Use descriptive prompts for better results: include genre, mood, tempo, and instruments
• Need a specific track length? Pass duration_seconds (clamped 5–600, then to the model's window). On Suno it works on suno-v6 and suno-v6-wild only, puts the request into custom mode, and does not work on suno-v6-mini; on ElevenLabs Music and the other length-controllable models it is required or you get a ~10s track. min_output_duration / max_output_duration are null for music models in GET /api/v1/models?type=music_gen, so read each model's summary there instead
• Poll at the cadence in poll_interval_hint (8 seconds for music)
• POST /v1/generate/music and the extend / cover / import / reference-audio / edit-section routes share the standard SDK generation bucket of 30 accepted requests/minute per account (the same bucket as video, Elements and chat). Rejected requests do not count against it. POST /v1/generate/music/composition-plan is outside that bucket

Related