Speech & Sound

GET /api/v1/voices

curl "https://api.kolbo.ai/api/v1/voices?gender=female" \
  -H "X-API-Key: kolbo_live_..."

{
  "success": true,
  "voices": [
    {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "name": "Rachel",
      "provider": "elevenlabs",
      "language": "English",
      "language_code": "en-US",
      "gender": "female",
      "accent": "American",
      "preview_url": "https://...",
      "thumbnail": "https://...",
      "description": "Calm, conversational narrator",
      "styles": ["conversational", "calm"],
      "v3_optimized": true,
      "custom": false
    },
    {
      "voice_id": "custom_68f2c1a9b4e5d6f7a8b9c0d1",
      "name": "My Cloned Voice",
      "provider": "elevenlabs",
      "language": "auto",
      "language_code": null,
      "gender": null,
      "accent": null,
      "preview_url": null,
      "thumbnail": null,
      "description": null,
      "styles": [],
      "v3_optimized": false,
      "voice_type": "clone",
      "voice_model_id": null,
      "custom": true
    }
  ],
  "count": 152
}

POST /api/v1/generate/speech

curl -X POST https://api.kolbo.ai/api/v1/generate/speech \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Kolbo AI, the all-in-one creative platform.",
    "voice": "Rachel"
  }'

curl -X POST https://api.kolbo.ai/api/v1/generate/speech \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Kolbo AI, the all-in-one creative platform.",
    "voice": "Rachel",
    "model": "eleven_v4"
  }'

curl -X POST https://api.kolbo.ai/api/v1/generate/speech \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Kolbo AI, the all-in-one creative platform.",
    "voice": "Rachel",
    "language": "en-US"
  }'

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "speech",
  "model": "eleven_v4",
  "credits_charged": 5,
  "poll_url": "/v1/generate/68f2c1a9b4e5d6f7a8b9c0d1/status",
  "poll_interval_hint": 8,
  "session_id": "68f2c1a9b4e5d6f7a8b9c0d2",
  "project_id": "68f2c1a9b4e5d6f7a8b9c0d3"
}

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "speech",
  "state": "completed",
  "progress": 100,
  "session_id": "68f2c1a9b4e5d6f7a8b9c0d2",
  "project_id": "68f2c1a9b4e5d6f7a8b9c0d3",
  "result": {
    "urls": ["https://media.kolbo.ai/tts/.../speech.mp3"],
    "voice": "EXAVITQu4vr4xnSDxMaL",
    "requested_voice_id": "EXAVITQu4vr4xnSDxMaL",
    "duration": null,
    "speaking_speed": null,
    "language": "en-US",
    "selected_style": null,
    "style_instructions": null,
    "style_instructions_label": null,
    "style_instructions_preset_id": null,
    "voice_settings": { "similarity_boost": 0.75, "style": 0.5, "stability": 1 },
    "model": "eleven_v4",
    "created_at": "2026-07-20T14:20:00Z"
  },
  "credits_used": 6,
  "credits_breakdown": [
    { "model": "eleven_v4", "amount": 6 }
  ]
}

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

async function generateSpeech() {
  const response = await fetch(`${BASE_URL}/v1/generate/speech`, {
    method: "POST",
    headers: {
      "X-API-Key": KOLBO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Welcome to Kolbo AI, the all-in-one creative platform.",
      voice: "Rachel",
    }),
  });

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

  const result = await pollUntilDone(started.generation_id, started.poll_interval_hint);
  if (result.state !== "completed") throw new Error(result.error || result.state);

  console.log("Audio URL:", result.result.urls[0]); // urls is always an array
  return result.result;
}

const TERMINAL = new Set(["completed", "failed", "cancelled"]);

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

generateSpeech().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/speech",
    headers={"X-API-Key": KOLBO_API_KEY},
    json={
        "text": "Welcome to Kolbo AI, the all-in-one creative platform.",
        "voice": "Rachel",
    },
)
started = response.json()
if not started.get("success"):
    raise Exception(started.get("error", "Request failed"))

TERMINAL = {"completed", "failed", "cancelled"}


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


result = poll_until_done(started["generation_id"], started["poll_interval_hint"])
if result["state"] != "completed":
    raise Exception(result.get("error", result["state"]))

print("Audio URL:", result["result"]["urls"][0])  # urls is always a list

POST /api/v1/generate/sound

curl -X POST https://api.kolbo.ai/api/v1/generate/sound \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Thunder clap followed by heavy rain"}'

curl -X POST https://api.kolbo.ai/api/v1/generate/sound \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Thunder clap followed by heavy rain",
    "model": "elevenlabs-sound-effects-v1"
  }'

curl -X POST https://api.kolbo.ai/api/v1/generate/sound \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Gentle ocean waves on a sandy beach",
    "duration": 10
  }'

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "sound",
  "model": "elevenlabs-sound-effects-v1",
  "credits_charged": 7,
  "poll_url": "/v1/generate/68f2c1a9b4e5d6f7a8b9c0d1/status",
  "poll_interval_hint": 5,
  "session_id": "68f2c1a9b4e5d6f7a8b9c0d2",
  "project_id": "68f2c1a9b4e5d6f7a8b9c0d3"
}

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "sound",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://media.kolbo.ai/sound/.../sfx.mp3"],
    "duration": 8,
    "prompt_used": "Thunder clap followed by heavy rain",
    "model": "elevenlabs-sound-effects-v1",
    "created_at": "2026-07-20T14:20:00Z"
  },
  "credits_used": 4,
  "credits_breakdown": [
    { "model": "elevenlabs-sound-effects-v1", "amount": 4 }
  ]
}

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

async function generateSound() {
  const response = await fetch(`${BASE_URL}/v1/generate/sound`, {
    method: "POST",
    headers: {
      "X-API-Key": KOLBO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Thunder clap followed by heavy rain",
    }),
  });

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

  // pollUntilDone() from the Text to Speech example above — same status route
  // and state machine, and poll_interval_hint is 5 seconds here instead of 8.
  const result = await pollUntilDone(started.generation_id, started.poll_interval_hint);
  if (result.state !== "completed") throw new Error(result.error || result.state);

  console.log("Sound URL:", result.result.urls[0]);
  return result.result;
}

generateSound().catch(console.error);

import requests

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

started = requests.post(
    f"{BASE_URL}/v1/generate/sound",
    headers={"X-API-Key": KOLBO_API_KEY},
    json={
        "prompt": "Thunder clap followed by heavy rain",
    },
).json()
if not started.get("success"):
    raise Exception(started.get("error", "Request failed"))

# poll_until_done() from the Text to Speech example above — same status route
# and state machine, and poll_interval_hint is 5 seconds here instead of 8.
result = poll_until_done(started["generation_id"], started["poll_interval_hint"])
if result["state"] != "completed":
    raise Exception(result.get("error", result["state"]))

print("Sound URL:", result["result"]["urls"][0])

POST /api/v1/voices/clone

curl -X POST https://api.kolbo.ai/api/v1/voices/clone \
  -H "X-API-Key: kolbo_live_..." \
  -F "[email protected]" \
  -F "voiceName=Narrator" \
  -F "provider=elevenlabs"

{
  "success": true,
  "voice": {
    "id": "",
    "name": "Narrator",
    "provider": "elevenlabs",
    "language": "english",
    "preview_audio_url": null
  }
}

POST /api/v1/voices/import-elevenlabs

curl -X POST https://api.kolbo.ai/api/v1/voices/import-elevenlabs \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "elevenLabsVoiceId": "21m00Tcm4TlvDq8ikWAM",
    "voiceId": "21m00Tcm4TlvDq8ikWAM"
  }'

DELETE /api/v1/voices/:id

curl -X DELETE https://api.kolbo.ai/api/v1/voices/68f2c1a9b4e5d6f7a8b9c0d1 \
  -H "X-API-Key: kolbo_live_..."