Integration docs for KaleidoVid speech, TTS, video flashcard, video, KDCN, and local LLM APIs.

x-api-key: kvid_your_prefix_your_secret

Reading Score, Shared LLM, TTS, Video Flashcards, LTX23 Video, and KDCN Video also accept:
Authorization: Bearer kvid_your_prefix_your_secret

Browser WebSocket clients should append `api_key=<YOUR_API_KEY>`
to the `ws_url` returned by POST /api/thai-asr/sessions.

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/thai-asr/config"

{
  "language": "th",
  "mode": "benchmark_spike",
  "backend": "persistent_decoder",
  "engine": "typhoon",
  "defaults": {
    "sample_rate": 16000,
    "frame_ms": 20,
    "stream_chunk_ms": 80,
    "partial_interval_ms": 40,
    "min_decode_audio_ms": 240,
    "decode_window_ms": 1600,
    "vad": true
  },
  "notes": [
    "This spike measures websocket, VAD, and partial transcript latency for Thai ASR on the 8x4090 host."
  ],
  "tenant": {
    "team_id": "team_cuid",
    "team_name": "Acme Team",
    "key_prefix": "abcd1234"
  },
  "limits": {
    "requests_per_minute": 120,
    "concurrent_sessions": 3,
    "daily_audio_seconds": 3600,
    "today_audio_seconds_used": 420
  }
}

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "sample_rate": 16000,
    "frame_ms": 20,
    "partial_interval_ms": 40,
    "min_decode_audio_ms": 240,
    "decode_window_ms": 1600,
    "vad": true
  }' \
  "https://kaleidovid.com/api/thai-asr/sessions"

{
  "session_id": "e6a4c4f6c69f4ca1aa8f9b3ad8d515f0",
  "mode": "benchmark_spike",
  "language": "th",
  "engine": "typhoon",
  "backend": "persistent_decoder",
  "ws_url": "wss://kaleidovid.com/api/thai-asr/stream?session_id=e6a4c4f6c69f4ca1aa8f9b3ad8d515f0",
  "config": {
    "sample_rate": 16000,
    "frame_ms": 20,
    "partial_interval_ms": 40,
    "min_decode_audio_ms": 240,
    "decode_window_ms": 1600,
    "vad": true,
    "benchmark_label": null
  },
  "sla_targets": {
    "speech_detected_p95_ms": 60,
    "first_partial_p95_ms": 250,
    "final_after_eou_p95_ms": 800
  },
  "tenant": {
    "team_id": "team_cuid",
    "team_name": "Acme Team",
    "key_prefix": "abcd1234"
  }
}

const API_KEY = "YOUR_API_KEY";
const HTTP_BASE = "https://kaleidovid.com";

const config = await fetch(`${HTTP_BASE}/api/thai-asr/config`, {
  headers: { "x-api-key": API_KEY },
}).then(async (response) => {
  if (!response.ok) throw new Error(await response.text());
  return response.json();
});

const session = await fetch(`${HTTP_BASE}/api/thai-asr/sessions`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    sample_rate: 16000,
    frame_ms: 20,
    partial_interval_ms: 40,
    min_decode_audio_ms: 240,
    decode_window_ms: 1600,
    vad: true,
  }),
}).then(async (response) => {
  if (!response.ok) throw new Error(await response.text());
  return response.json();
});

const wsUrl = `${session.ws_url}&api_key=${encodeURIComponent(API_KEY)}`;
const socket = new WebSocket(wsUrl);

socket.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  switch (payload.type) {
    case "ready":
      socket.send(JSON.stringify({
        type: "start",
        sample_rate: 16000,
        frame_ms: 20,
        partial_interval_ms: 40,
        min_decode_audio_ms: 240,
        decode_window_ms: 1600,
        vad: true,
      }));
      break;
    case "partial":
    case "stabilized_partial":
      console.log("live", payload.text);
      break;
    case "final":
      console.log("final", payload.text, payload.segments);
      break;
    case "error":
      console.error(payload.code, payload.error);
      break;
  }
};

// `pcmChunks` must contain raw PCM16LE mono audio frames.
// Do not send WAV headers after the socket is started.
for (const chunk of pcmChunks) {
  socket.send(chunk);
}

socket.send(JSON.stringify({ type: "flush" }));
socket.send(JSON.stringify({ type: "end" }));

{
  "type": "final",
  "session_id": "e6a4c4f6c69f4ca1aa8f9b3ad8d515f0",
  "engine": "typhoon",
  "backend": "persistent_decoder",
  "text": "สวัสดีครับ นี่คือการทดสอบระบบถอดเสียงภาษาไทยแบบหน่วงต่ำ",
  "segments": [
    {
      "start": 0.0,
      "end": 2.84,
      "text": "สวัสดีครับ นี่คือการทดสอบระบบถอดเสียงภาษาไทยแบบหน่วงต่ำ"
    }
  ],
  "audio_ms": 2840,
  "latency_ms": 134,
  "queue_ms": 0,
  "decode_ms": 134,
  "processing_time_ms": 133,
  "audio_duration_ms": 2840
}

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  -F "student_audio=@student.wav" \
  -F "reference_text=สวัสดีครับ วันนี้เราจะเรียนภาษาไทย" \
  -F "student_id=student_001" \
  -F "lesson_id=lesson_01" \
  -F "language=th" \
  -F "include_pronunciation=true" \
  "https://kaleidovid.com/api/reading-score"

# pip install requests

import json
import time
import requests

ENDPOINT_URL = "https://kaleidovid.com/api/reading-score"
BASE_URL = ENDPOINT_URL.removesuffix("/api/reading-score")
API_KEY = "YOUR_API_KEY"

def read_result_or_poll(response):
    if response.status_code != 202:
        response.raise_for_status()
        return response.json()

    queued = response.json()
    status_path = queued.get("statusPath")
    if not status_path:
        return queued

    while True:
        status_response = requests.get(
            f"{BASE_URL}{status_path}",
            headers={"x-api-key": API_KEY},
            timeout=30,
        )
        status_response.raise_for_status()
        status_payload = status_response.json()
        if not status_payload.get("ready"):
            time.sleep(2)
            continue
        if status_payload.get("successful"):
            return status_payload.get("result")
        raise RuntimeError(status_payload.get("error", "Reading score failed"))

with open("student.wav", "rb") as student_audio:
    response = requests.post(
        ENDPOINT_URL,
        headers={"x-api-key": API_KEY},
        data={
            "reference_text": "สวัสดีครับ วันนี้เราจะเรียนภาษาไทย",
            "student_id": "student_001",
            "lesson_id": "lesson_01",
            "language": "th",
            "include_pronunciation": "true",
        },
        files={
            "student_audio": ("student.wav", student_audio, "audio/wav"),
        },
        timeout=300,
    )

payload = read_result_or_poll(response)
print(json.dumps(payload, ensure_ascii=False, indent=2))

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/llm/v1/models"

{
  "object": "list",
  "data": [
    {
      "id": "qwen3-4b",
      "object": "model",
      "owned_by": "kaleidovid-local"
    }
  ]
}

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "qwen3-4b",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Explain why a shared local LLM endpoint is useful." }
    ],
    "temperature": 0.4,
    "max_tokens": 256
  }' \
  "https://kaleidovid.com/api/llm/v1/chat/completions"

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://kaleidovid.com/api/llm/v1",
)

response = client.chat.completions.create(
    model="qwen3-4b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain the API in one short paragraph."},
    ],
    temperature=0.4,
    max_tokens=256,
)

print(response.choices[0].message.content)

curl -sS \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio_file=@thai-ref-female-4s.wav;type=audio/wav" \
  -F "name=thai_flashcard_female" \
  -F "model=omnivoice" \
  -F "language=th" \
  -F "transcript=reference transcript here" \
  "https://kaleidovid.com/api/tts/v1/custom-voices"

{
  "success": true,
  "voice": {
    "id": "cv_123",
    "name": "thai_flashcard_female",
    "model": "omnivoice",
    "language": "th",
    "audioPath": "custom_voices/user-1/thai_flashcard_female.wav",
    "transcript": "reference transcript here"
  },
  "clone_audio": "custom_voices/user-1/thai_flashcard_female.wav",
  "clone_text": "reference transcript here",
  "ttsRequest": {
    "clone_audio": "custom_voices/user-1/thai_flashcard_female.wav",
    "clone_text": "reference transcript here"
  }
}

curl -sS \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio_url=https://example.com/tts_refs/thai-ref-female-4s.wav" \
  -F "name=thai_flashcard_female" \
  -F "model=omnivoice" \
  -F "language=th" \
  "https://kaleidovid.com/api/tts/v1/custom-voices"

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "text": "สวัสดีครับ",
    "language": "th",
    "model": "omnivoice",
    "clone_audio": "custom_voices/user-1/thai_flashcard_female.wav",
    "clone_text": "reference transcript here",
    "seed": 12345
  }' \
  "https://kaleidovid.com/api/tts/v1/audio/speech"

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "text": "Hello from the KaleidoVid TTS API.",
    "language": "en",
    "model": "cosytts",
    "speaker": "Ryan",
    "instruct": "Warm, clear narration",
    "seed": 12345
  }' \
  "https://kaleidovid.com/api/tts/v1/audio/speech"

{
  "success": true,
  "taskId": "a97bf5a8-16d4-44c7-b45b-c8a5f94c9e8f",
  "message": "TTS generation task started with COSYTTS",
  "statusPath": "/api/tts/v1/audio/speech/a97bf5a8-16d4-44c7-b45b-c8a5f94c9e8f"
}

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/tts/v1/audio/speech/a97bf5a8-16d4-44c7-b45b-c8a5f94c9e8f"

{
  "taskId": "a97bf5a8-16d4-44c7-b45b-c8a5f94c9e8f",
  "state": "SUCCESS",
  "ready": true,
  "successful": true,
  "result": {
    "success": true,
    "url": "/uploads/generations/tts/tts_cosytts_20260605_1234.wav",
    "metadata": {
      "text": "Hello from the KaleidoVid TTS API.",
      "language": "en",
      "model": "cosytts",
      "duration": 2.14,
      "seed": 12345
    }
  }
}

# pip install requests

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://kaleidovid.com/api/tts/v1"

start = requests.post(
    f"{BASE_URL}/audio/speech",
    headers={"x-api-key": API_KEY},
    json={
        "text": "Hello from the KaleidoVid TTS API.",
        "language": "en",
        "model": "cosytts",
        "speaker": "Ryan",
        "instruct": "Warm, clear narration",
    },
    timeout=180,
)
start.raise_for_status()
task_id = start.json()["taskId"]

while True:
    status = requests.get(f"{BASE_URL}/audio/speech/{task_id}", headers={"x-api-key": API_KEY}, timeout=60)
    status.raise_for_status()
    payload = status.json()
    if payload.get("ready"):
        break
    time.sleep(3)

if not payload.get("successful"):
    raise RuntimeError(payload.get("error", "TTS generation failed"))

print(payload["result"]["url"])

{
  "taskId": "a97bf5a8-16d4-44c7-b45b-c8a5f94c9e8f",
  "state": "FAILURE",
  "ready": true,
  "successful": false,
  "error": "TTS generation failed: upstream message"
}

curl -sS \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -F "video_file=@lesson.mp4;type=video/mp4" \
  -F "learning_direction=thai_to_chinese" \
  -F "max_words_per_segment=8" \
  -F "include_rendered_segments=true" \
  -F "include_original_segments=true" \
  -F "idempotency_key=lesson-001-th-zh" \
  "https://kaleidovid.com/api/video-flashcards/v1/jobs"

{
  "success": true,
  "job_id": "vf_clxq3videojob",
  "status": "queued",
  "statusPath": "/api/video-flashcards/v1/jobs/vf_clxq3videojob",
  "limits": {
    "requests_per_minute": 120,
    "concurrent_video_jobs": 3,
    "daily_video_minutes": 60,
    "today_video_minutes_used": null,
    "max_video_duration_seconds": 900,
    "max_upload_bytes": 524288000
  }
}

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "source_type": "youtube",
    "learning_direction": "japanese_to_chinese",
    "skip_vocal_separation": true,
    "max_words_per_segment": 10,
    "idempotency_key": "yt-lesson-001-ja-zh"
  }' \
  "https://kaleidovid.com/api/video-flashcards/v1/jobs/from-url"

# pip install requests

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://kaleidovid.com/api/video-flashcards/v1"

with open("lesson.mp4", "rb") as video:
    start = requests.post(
        f"{BASE_URL}/jobs",
        headers={"x-api-key": API_KEY},
        data={
            "learning_direction": "thai_to_chinese",
            "max_words_per_segment": "8",
            "include_rendered_segments": "true",
            "include_original_segments": "true",
            "idempotency_key": "lesson-001-th-zh",
        },
        files={"video_file": ("lesson.mp4", video, "video/mp4")},
        timeout=300,
    )

start.raise_for_status()
job_id = start.json()["job_id"]

while True:
    status = requests.get(f"{BASE_URL}/jobs/{job_id}", headers={"x-api-key": API_KEY}, timeout=60)
    status.raise_for_status()
    payload = status.json()
    if payload["ready"]:
        break
    time.sleep(5)

if not payload["successful"]:
    raise RuntimeError(payload["error"]["message"])

for segment in payload["result"]["segments"]:
    print(segment["text"], "=>", segment["translation"])
    print(segment["video"]["rendered_segment_url"])

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/video-flashcards/v1/jobs/vf_clxq3videojob"

{
  "job_id": "vf_clxq3videojob",
  "status": "processing",
  "ready": false,
  "successful": null,
  "progress": {
    "percent": 42,
    "stage": "translating",
    "message": "translating"
  },
  "media": {
    "title": "lesson",
    "duration": 312.4
  }
}

{
  "job_id": "vf_clxq3videojob",
  "status": "done",
  "ready": true,
  "successful": true,
  "progress": {
    "percent": 100,
    "stage": "done",
    "message": "done"
  },
  "media": {
    "title": "lesson",
    "duration": 312.4
  },
  "result": {
    "learning_direction": "thai_to_chinese",
    "source_language": "th",
    "target_language": "zh",
    "media": {
      "title": "lesson",
      "duration": 312.4,
      "source_url": null,
      "original_video_url": "/uploads/video-flashcards/imports/user-1/lesson.mp4"
    },
    "transcript": {
      "text": "สวัสดีครับ วันนี้เราจะเรียนคำศัพท์ใหม่",
      "language": "th",
      "segments": [
        {
          "index": 0,
          "start": 1.2,
          "end": 4.6,
          "text": "สวัสดีครับ วันนี้เราจะเรียนคำศัพท์ใหม่"
        }
      ]
    },
    "segments": [
      {
        "index": 0,
        "start": 1.2,
        "end": 4.6,
        "duration": 3.4,
        "text": "สวัสดีครับ วันนี้เราจะเรียนคำศัพท์ใหม่",
        "translation": "你好，今天我们会学习新词。",
        "translation_en": "Hello, today we will learn new vocabulary.",
        "word_items": [
          {
            "word": "สวัสดี",
            "pronunciation": "sa-wat-dee",
            "meaning": "你好",
            "meaning_en": "hello",
            "start": 1.2,
            "end": 1.82,
            "probability": 0.94
          }
        ],
        "video": {
          "original_segment_url": "/uploads/flashcards/original_segments/segment_000.mp4",
          "rendered_segment_url": "/uploads/flashcards/rendered_segments/segment_000.mp4",
          "content_type": "video/mp4",
          "has_word_cards": true
        }
      }
    ]
  }
}

{
  "job_id": "vf_clxq3videojob",
  "status": "failed",
  "ready": true,
  "successful": false,
  "progress": {
    "percent": 64,
    "stage": "asr",
    "message": "asr"
  },
  "media": {
    "title": "lesson",
    "duration": 312.4
  },
  "error": {
    "code": "processing_failed",
    "message": "Video flashcard job failed"
  }
}

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "ltx23-standard",
    "prompt": "A cinematic product shot with gentle camera motion.",
    "image": {
      "url": "https://example.com/input.png"
    },
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "seed": -1
  }' \
  "https://kaleidovid.com/api/ltx23/v1/videos/generations"

{
  "request_id": "6bcd2f29-4b74-4479-a3b3-f71a50a77dab",
  "status": "queued",
  "model": "ltx23-standard"
}

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/ltx23/v1/videos/6bcd2f29-4b74-4479-a3b3-f71a50a77dab"

{
  "request_id": "6bcd2f29-4b74-4479-a3b3-f71a50a77dab",
  "status": "done",
  "model": "ltx23-standard",
  "video": {
    "url": "/uploads/generations/ltx23/ltx23_av_20260426_abcdef.mp4"
  }
}

# pip install requests

import base64
import mimetypes
import time
from pathlib import Path

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://kaleidovid.com/api/ltx23/v1"
image_path = Path("input.png")
mime_type = mimetypes.guess_type(image_path.name)[0] or "image/png"
image_data_url = (
    f"data:{mime_type};base64,"
    + base64.b64encode(image_path.read_bytes()).decode("ascii")
)

start = requests.post(
    f"{BASE_URL}/videos/generations",
    headers={"x-api-key": API_KEY},
    json={
        "model": "ltx23-standard",
        "prompt": "A cinematic product shot with gentle camera motion.",
        "image": {"url": image_data_url},
        "duration": 5,
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "seed": -1,
    },
    timeout=180,
)
start.raise_for_status()
request_id = start.json()["request_id"]

while True:
    status = requests.get(f"{BASE_URL}/videos/{request_id}", headers={"x-api-key": API_KEY}, timeout=60)
    status.raise_for_status()
    payload = status.json()
    if payload["status"] in {"done", "failed", "canceled"}:
        break
    time.sleep(5)

print(payload)

{
  "request_id": "6bcd2f29-4b74-4479-a3b3-f71a50a77dab",
  "status": "failed",
  "model": "ltx23-standard",
  "error": "Remote LTX image-to-video failed: upstream message"
}

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/kdcn/v1/models"

{
  "object": "list",
  "provider": "kdcn",
  "base_url": "/api/kdcn/v1/videos",
  "data": [
    {
      "id": "kdcn:xai-grok-imagine-image-to-video-official-stable",
      "title": "Xai-grok-imagine-image-to-video-official-stable",
      "category": "image-to-video",
      "required": ["prompt", "imageUrl"],
      "parameters": [
        { "name": "prompt", "type": "string", "required": true },
        { "name": "imageUrl", "type": "string", "format": "uri", "required": true }
      ]
    }
  ]
}

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
    "prompt": "A calm cinematic camera push over the product.",
    "inputs": {
      "images": [
        { "url": "https://example.com/product.png" }
      ]
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "options": {
      "movementAmplitude": "auto"
    }
  }' \
  "https://kaleidovid.com/api/kdcn/v1/videos/generations"

{
  "request_id": "a4377c13-c2a6-4974-81df-0f0ccbf701dc",
  "status": "queued",
  "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
  "provider": "kdcn"
}

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/kdcn/v1/videos/a4377c13-c2a6-4974-81df-0f0ccbf701dc"

{
  "request_id": "a4377c13-c2a6-4974-81df-0f0ccbf701dc",
  "status": "done",
  "provider": "kdcn",
  "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
  "video": {
    "url": "/uploads/generations/video/runninghub_image-to-video/clip.mp4"
  }
}

# pip install requests

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://kaleidovid.com/api/kdcn/v1"

start = requests.post(
    f"{BASE_URL}/videos/generations",
    headers={"x-api-key": API_KEY},
    json={
        "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
        "prompt": "A calm cinematic camera push over the product.",
        "inputs": {
            "images": [{"url": "https://example.com/product.png"}],
        },
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "options": {"movementAmplitude": "auto"},
    },
    timeout=180,
)
start.raise_for_status()
request_id = start.json()["request_id"]

while True:
    status = requests.get(f"{BASE_URL}/videos/{request_id}", headers={"x-api-key": API_KEY}, timeout=60)
    status.raise_for_status()
    payload = status.json()
    if payload["status"] in {"done", "failed", "canceled"}:
        break
    time.sleep(5)

print(payload)

{
  "request_id": "a4377c13-c2a6-4974-81df-0f0ccbf701dc",
  "status": "failed",
  "provider": "kdcn",
  "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
  "error": "KDCN generation failed: upstream message"
}