Lipsync

POST /api/v1/generate/lipsync

curl -X POST https://api.kolbo.ai/api/v1/generate/lipsync \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/two-people.mp4",
    "audio_url": "https://example.com/speech.mp3",
    "model": "fal-ai/sync-lipsync/v3",
    "emotion": "happy",
    "active_speaker_detection": { "coordinates": [640, 360], "frame_number": 30 }
  }'

curl -X POST https://api.kolbo.ai/api/v1/generate/lipsync \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/portrait.jpg",
    "audio_url": "https://example.com/speech.mp3"
  }'

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

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

curl -X POST https://api.kolbo.ai/api/v1/generate/lipsync \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -F "source_url=https://example.com/portrait.jpg" \
  -F "[email protected]"

curl -X POST https://api.kolbo.ai/api/v1/generate/lipsync \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/portrait.jpg",
    "audio_url": "https://example.com/speech.mp3",
    "model": "your-model-identifier"
  }'

const API_KEY = "kolbo_live_YOUR_API_KEY";

// Fetch available lipsync models
async function initModels() {
  const res = await fetch("https://api.kolbo.ai/api/v1/models?type=lipsync", {
    headers: { "X-API-Key": API_KEY },
  });
  const data = await res.json();
  console.log("Available models:", data.models.map((m) => m.identifier));
}

async function main() {
  await initModels();

  // Using URLs (Smart Select)
  const response = await fetch("https://api.kolbo.ai/api/v1/generate/lipsync", {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      source_url: "https://example.com/portrait.jpg",
      audio_url: "https://example.com/speech.mp3",
    }),
  });

  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("Video URL:", result.result.urls[0]); // urls is always an array
}

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(
      `https://api.kolbo.ai/api/v1/generate/${generationId}/status`,
      { headers: { "X-API-Key": API_KEY } }
    ).then((r) => r.json());
    if (TERMINAL.has(status.state)) return status;
  }
}

main();

import requests
import time

API_KEY = "kolbo_live_YOUR_API_KEY"
BASE_URL = "https://api.kolbo.ai/api"
HEADERS = {"X-API-Key": API_KEY}

# Fetch available lipsync models
models_res = requests.get(
    f"{BASE_URL}/v1/models",
    headers=HEADERS,
    params={"type": "lipsync"},
)
print("Available models:", [m["identifier"] for m in models_res.json()["models"]])

# --- Option A: Using URLs (Smart Select) ---
response = requests.post(
    f"{BASE_URL}/v1/generate/lipsync",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "source_url": "https://example.com/portrait.jpg",
        "audio_url": "https://example.com/speech.mp3",
    },
)

data = response.json()
print("Generation ID:", data["generation_id"])

# --- Option B: Using file uploads ---
# with open("portrait.jpg", "rb") as img, open("speech.mp3", "rb") as aud:
#     response = requests.post(
#         f"{BASE_URL}/v1/generate/lipsync",
#         headers=HEADERS,
#         files={"image": img, "audio": aud},
#     )
#     data = response.json()

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

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

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

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

{
  "success": true,
  "generation_id": "6820f1c2a1b2c3d4e5f60718",
  "type": "lipsync",
  "model": "auto",
  "credits_charged": null,
  "poll_url": "/v1/generate/6820f1c2a1b2c3d4e5f60718/status",
  "poll_interval_hint": 8,
  "session_id": "6820f1c2a1b2c3d4e5f60700",
  "project_id": "6820f1c2a1b2c3d4e5f606ff"
}

{
  "success": true,
  "generation_id": "6820f1c2a1b2c3d4e5f60718",
  "type": "lipsync",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://media.kolbo.ai/videos/.../lipsync.mp4"],
    "thumbnail_url": "https://media.kolbo.ai/videos/.../thumb.jpg",
    "duration": null,
    "aspect_ratio": "16:9",
    "model": null,
    "created_at": "2026-04-12T10:00:00.000Z"
  },
  "credits_used": 40,
  "credits_breakdown": [
    { "model": "MODEL_IDENTIFIER", "amount": 40, "base": 40, "final": 40, "duration_multiplier": 1, "pricing": null }
  ]
}