Karaoke API

Karaoke Sync API

Submit an MP3 audio file with pre-segmented lyrics and receive word-level timestamps for karaoke synchronization. Results are delivered asynchronously and stored for 90 days.

Authentication

All API requests require an API key sent via the X-API-Key header.

X-API-Key: kk_your_api_key_here

API keys are provided by the platform administrator. Keys prefixed with kk_ are Karaoke API keys.

POST /api/v1/sync

Submit an alignment job. Returns immediately with a job ID. Results are delivered asynchronously.

Request

Content-Type: multipart/form-data

Example

curl -X POST https://karaoke.cohesium.ai/api/v1/sync \
  -H "X-API-Key: kk_your_api_key_here" \
  -F "audio=@song.mp3" \
  -F "lyrics=Joyeux anniversaire
Cher Antoine
On te souhaite
Plein de bonheur" \
  -F "language=fr"

Response 202 Accepted

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "created_at": "2026-04-04T10:30:00Z"
}

GET /api/v1/sync/{job_id}

Retrieve the status and result of an alignment job. Results are available for 90 days after completion.

Example

curl https://karaoke.cohesium.ai/api/v1/sync/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: kk_your_api_key_here"

Response 200 OK (completed)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "created_at": "2026-04-04T10:30:00Z",
  "completed_at": "2026-04-04T10:30:12Z",
  "expires_at": "2026-07-03T10:30:12Z",
  "result": {
    "segments": [
      {
        "index": 0,
        "text": "Joyeux anniversaire",
        "start": 5.240,
        "end": 7.810,
        "words": [
          { "word": "Joyeux",       "start": 5.240, "end": 5.880, "confidence": 0.94 },
          { "word": "anniversaire", "start": 5.920, "end": 7.810, "confidence": 0.89 }
        ]
      }
    ],
    "statistics": {
      "total_segments": 4,
      "total_words": 12,
      "avg_confidence": 0.87,
      "low_confidence_words": 1,
      "duration_s": 30.5
    }
  }
}

Response 202 Accepted (still processing)

{
  "job_id": "a1b2c3d4-...",
  "status": "processing",
  "created_at": "2026-04-04T10:30:00Z"
}

Response 410 Gone (expired)

{
  "error": {
    "code": "RESULT_EXPIRED",
    "message": "Result expired after 90 days"
  }
}

GET /api/v1/health

Health check endpoint. No authentication required.

{ "status": "healthy" }

Error Codes

All errors follow the format: {"error": {"code": "...", "message": "..."}}

Lyrics Guidelines

Limits