Tonael

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 Tonael 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.

Query Parameters

Export Examples

# Get as Enhanced LRC (karaoke)
curl "https://karaoke.cohesium.ai/api/v1/sync/{job_id}?format=lrc" -H "X-API-Key: ..."

# Get as SRT (subtitles)
curl "https://karaoke.cohesium.ai/api/v1/sync/{job_id}?format=srt" -H "X-API-Key: ..."

# Get as WebVTT (web video)
curl "https://karaoke.cohesium.ai/api/v1/sync/{job_id}?format=vtt" -H "X-API-Key: ..."

# Get as ASS (video karaoke with word highlighting)
curl "https://karaoke.cohesium.ai/api/v1/sync/{job_id}?format=ass" -H "X-API-Key: ..."

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"
  }
}

DELETE /api/v1/sync/{job_id}

Cancel a job that is still in the queue. Only jobs with status queued can be cancelled. Jobs that are already processing, completed, or failed cannot be cancelled.

Example

curl -X DELETE https://karaoke.cohesium.ai/api/v1/sync/{job_id} \
  -H "X-API-Key: kk_your_api_key_here"

Response 200 OK

{ "job_id": "...", "status": "cancelled" }

Response 409 Conflict (not cancellable)

{ "error": { "code": "NOT_CANCELLABLE", "message": "Job is 'processing' — only 'queued' jobs can be cancelled" } }

GET /api/v1/health

Health check endpoint. No authentication required. Returns the status of all system components.

Response 200 OK (all systems operational)

{
  "status": "healthy",
  "service": "tonael-sync",
  "version": "1.0.0",
  "checks": {
    "api": "ok",
    "database": "ok",
    "processing": "ok"
  }
}

Response 503 Service Unavailable (degraded)

{
  "status": "degraded",
  "service": "tonael-sync",
  "version": "1.0.0",
  "checks": {
    "api": "ok",
    "database": "ok",
    "processing": "down"
  }
}

Use this endpoint for uptime monitoring. Status healthy = all systems go. degraded = partial outage. unhealthy = critical failure.

Error Codes

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

Lyrics Guidelines

What you should do

What the API handles automatically

Limits