Transcription

POST /api/v1/transcribe

curl -X POST https://api.kolbo.ai/api/v1/transcribe \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/podcast-episode.mp3"}'

curl -X POST https://api.kolbo.ai/api/v1/transcribe \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://example.com/interview.mp4"}'

curl -X POST https://api.kolbo.ai/api/v1/transcribe \
  -H "X-API-Key: kolbo_live_..." \
  -F "[email protected]"

curl -X POST https://api.kolbo.ai/api/v1/transcribe \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/interview.mp3",
    "diarize": true,
    "words_per_line": 6,
    "lines_per_subtitle": 2,
    "stretch_captions": false
  }'

curl -X POST https://api.kolbo.ai/api/v1/transcribe \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/hebrew-interview.mp4",
    "language": "en"
  }'

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "transcription",
  "model": "auto",
  "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": "transcription",
  "state": "completed",
  "progress": 100,
  "result": {
    "text": "Speaker 1 [0:00 - 0:12]:\nHello and welcome to today's episode...",
    "words": [
      { "text": "Hello", "start": 0.0, "end": 0.42 },
      { "text": "and", "start": 0.42, "end": 0.6 }
    ],
    "srt_url": "https://media.kolbo.ai/stt/.../subtitles.srt",
    "txt_url": "https://media.kolbo.ai/stt/.../transcript.txt",
    "word_by_word_srt_url": "https://media.kolbo.ai/stt/.../words.srt",
    "srt_content": "1\n00:00:00,000 --> 00:00:03,500\nHello and welcome to today's episode\n\n",
    "duration": 245.8,
    "audio_url": "https://media.kolbo.ai/uploaded-audio/.../episode-42.mp3",
    "model": null,
    "created_at": "2026-07-20T14:20:00Z"
  }
}

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

async function transcribe(body) {
  const response = await fetch(`${BASE_URL}/api/v1/transcribe`, {
    method: "POST",
    headers: {
      "X-API-Key": KOLBO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

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

  const status = await pollUntilDone(started.generation_id, started.poll_interval_hint);
  if (status.state !== "completed") throw new Error(status.error || status.state);
  return status.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}/api/v1/generate/${generationId}/status`,
      { headers: { "X-API-Key": KOLBO_API_KEY } }
    ).then((r) => r.json());
    if (TERMINAL.has(status.state)) return status;
  }
}

async function main() {
  // Transcribe from audio URL
  const result = await transcribe({
    audio_url: "https://example.com/podcast.mp3",
  });

  console.log("Full text:", result.text); // the transcript — no urls array here
  console.log("Duration:", result.duration, "seconds");
  console.log("SRT file:", result.srt_url);
  console.log("Word-level SRT:", result.word_by_word_srt_url);
}

main().catch(console.error);

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

async function transcribeFile(filePath) {
  // Node.js: use fs to read the file
  const fs = await import("fs");
  const path = await import("path");

  const formData = new FormData();
  formData.append("file", new Blob([fs.readFileSync(filePath)]), path.basename(filePath));

  const response = await fetch(`${BASE_URL}/api/v1/transcribe`, {
    method: "POST",
    headers: { "X-API-Key": KOLBO_API_KEY },
    body: formData,
  });

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

  // pollUntilDone() from the URL-input example above — a file upload returns the
  // same envelope and is polled the same way.
  const status = await pollUntilDone(started.generation_id, started.poll_interval_hint);
  if (status.state !== "completed") throw new Error(status.error || status.state);
  return status.result;
}

async function main() {
  const result = await transcribeFile("./recording.mp3");
  console.log("Transcript:", result.text);
  console.log("SRT download:", result.srt_url);
}

main().catch(console.error);

import requests
import time

KOLBO_API_KEY = "kolbo_live_..."  # Replace with your API key
BASE_URL = "https://api.kolbo.ai"
HEADERS = {"X-API-Key": KOLBO_API_KEY}

# Transcribe from audio URL
response = requests.post(
    f"{BASE_URL}/api/v1/transcribe",
    headers=HEADERS,
    json={"audio_url": "https://example.com/podcast.mp3"},
)
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}/api/v1/generate/{generation_id}/status",
            headers=HEADERS,
        ).json()
        if status["state"] in TERMINAL:
            return status


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

result = status["result"]
print("Full text:", result["text"])  # the transcript — no urls array here
print("Duration:", result["duration"], "seconds")
print("SRT file:", result["srt_url"])
print("Word-level SRT:", result["word_by_word_srt_url"])

import requests

KOLBO_API_KEY = "kolbo_live_..."  # Replace with your API key
BASE_URL = "https://api.kolbo.ai"
HEADERS = {"X-API-Key": KOLBO_API_KEY}

# Upload a local file
with open("recording.mp3", "rb") as f:
    started = requests.post(
        f"{BASE_URL}/api/v1/transcribe",
        headers=HEADERS,
        files={"file": ("recording.mp3", f)},
    ).json()

if not started.get("success"):
    raise Exception(started.get("error", "Request failed"))

# poll_until_done() from the URL-input example above — a file upload returns the
# same envelope and is polled the same way.
status = poll_until_done(started["generation_id"], started["poll_interval_hint"])
if status["state"] != "completed":
    raise Exception(status.get("error", status["state"]))

result = status["result"]
print("Transcript:", result["text"])
print("SRT download:", result["srt_url"])
print("Text download:", result["txt_url"])