Tonael API

Submit an MP3 audio file with pre-segmented lyrics and receive word-level timestamps for karaoke synchronization. Results are delivered asynchronously and retained per tier: 24 hours for hot (real-time) jobs, 72 hours for batch jobs.

Authentication

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

X-API-Key: ton_your_api_key_here

API keys are provided by the platform administrator. Keys prefixed with ton_ are Tonael keys.

Free Tier & Sign-up

Start free — 10 free minutes of tonael, no card required. Add a card and your allowance grows to 30 free minutes. The grant lands as credit on your balance, so you choose which model to spend it on — the minutes quoted are at the tonael hot rate, so tonael_ultra draws it down faster and batch stretches it further. Free-tier keys run on hot (real-time) processing with a small concurrency cap; making your first top-up lifts those limits and unlocks batch processing.

POST /api/v1/signup

Create an account from an email address. The API key is returned exactly once. Your free minutes unlock after you verify your email.

curl -X POST https://tonael.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

GET /api/v1/verify

Redeem the verification token from your sign-up email. Verifying your email releases the free credit.

curl "https://tonael.com/api/v1/verify?token=your_verification_token"

Pricing & Metering

You are billed per second of audio, rounded up, with a 30-second minimum per job. Prices are in USD, exclusive of VAT/sales tax.

A 3.5-minute song costs from $0.16 (tonael) or $0.33 (tonael_ultra) at hot rates. Batch has a 24-hour window: a batch job starts within 24 hours, or it is rejected and fully refunded, and its result stays available for 72 hours — see Batch processing. Processing more than 10,000 minutes/month? Talk to us.

Failed jobs are never charged. If a job fails or is cancelled, the reserved amount is automatically re-credited to your balance.

Credits

Credit is prepaid. Buy a pack — $15, $50, or $200 — or top up a custom amount. Minimum top-up: $15. Jobs draw down your balance as they are metered.

GET /api/v1/credits/balance

Return the current balance in dollars.

curl https://tonael.com/api/v1/credits/balance \
  -H "X-API-Key: ton_your_api_key_here"

{ "balance_usd": "42.50" }

POST /api/v1/credits/topup

Charge your registered card for a credit pack (pack_15, pack_25, pack_50, pack_100, pack_200) or a custom amount_usd (minimum 15). Provide exactly one of the two.

Before your first top-up, set your billing details once via POST /api/v1/credits/tax-identity (country, is_business, and for an EU business an optional vat_number). They determine the VAT on your invoice, so a top-up before they are set returns 422 TAX_IDENTITY_REQUIRED.

An Idempotency-Key header is required. Generate one value per purchase (a UUID is ideal) and reuse that same value if you retry a request that timed out or failed with a network error — that is what guarantees your card is charged only once. A repeat of a key that already went through returns 409 DUPLICATE_SUBMISSION instead of charging again.

curl -X POST https://tonael.com/api/v1/credits/topup \
  -H "X-API-Key: ton_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ea3f-4d1b-9a2c-7b6c0d5e1a90" \
  -d '{"pack": "pack_50"}'

{ "status": "credited", "amount_usd": "$50.00", "balance_usd": "92.50" }

Credits are prepaid and non-refundable, and never expire. Failed or cancelled jobs are automatically re-credited to your balance; no cash refunds are issued.

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://tonael.com/api/v1/sync \
  -H "X-API-Key: ton_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 24 hours after completion for hot jobs, and 72 hours for batch jobs. After that window the endpoint returns 410 Gone.

Query Parameters

Export Examples

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

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

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

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

Example

curl https://tonael.com/api/v1/sync/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: ton_your_api_key_here"

Response 200 OK (completed)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "language": "fr",
  "model": "tonael",
  "product_type": "sync_tonael",
  "created_at": "2026-04-04T10:30:00Z",
  "completed_at": "2026-04-04T10:30:12Z",
  "expires_at": "2026-04-05T10:30:12Z",
  "result": {
    "processing": { "processing_time_ms": 3437 },
    "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,
        "unaligned_words": 0,
        "duration_s": 30.5
      }
    }
  }
}

Per-letter timestamps (default)

By default (no granularity param), each word carries both its own timestamps and a nested chars array of per-letter timestamps. Pass granularity=word for a lighter, word-only response with no chars array. Word-level fields are identical either way, and the price is the same.

{
  "word": "café",
  "start": 5.240,
  "end": 5.880,
  "confidence": 0.94,
  "chars": [
    { "char": "c", "start": 5.240, "end": 5.360, "confidence": 0.95 },
    { "char": "a", "start": 5.360, "end": 5.520, "confidence": 0.93 },
    { "char": "f", "start": 5.520, "end": 5.700, "confidence": 0.92 },
    { "char": "é", "start": 5.700, "end": 5.880, "confidence": 0.90 }
  ]
}

Notes: character timestamps are approximately 20 ms in resolution. Some characters — punctuation, and certain diacritics or accents — may not receive an independent timestamp, so a word's chars array can be shorter than its letter count. Characters are always returned in reading order with non-decreasing start times within a word.

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 has expired and is no longer available",
    "details": "Results are retained for 24 hours (72 hours for batch jobs)"
  }
}

DELETE /api/v1/sync/{job_id}

Cancel a job that is still in the queue — typically a batch job waiting for its window — and get its reserved amount back in full. Only jobs with status queued can be cancelled. The same call cancels a queued stem separation or karaoke video: DELETE /api/v1/stems/{job_id} and DELETE /api/v1/video/{job_id}.

A 409 NOT_CANCELLABLE means the job can no longer be cancelled: it is processing or finished, or it was already claimed for processing. A batch job can still read queued for a moment after it is claimed, so a 409 on a queued job means its processing has started.

Example

curl -X DELETE https://tonael.com/api/v1/sync/{job_id} \
  -H "X-API-Key: ton_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" } }

Batch Processing

Not in a hurry? Submit with priority=batch for a lower rate. Batch has a 24-hour window: a batch job starts within 24 hours, or it is rejected and fully refunded — or switched to hot, if you ask for it. Its result stays available for 72 hours after completion. Batch is opportunistic and available on paid accounts; make your first top-up to unlock it.

• Same endpoints, same request shape — add priority=batch, and optionally batch_fallback and callback_url, with the same names and values on every endpoint above. A video render still requires callback_url; its webhook_secret is optional in batch and has no effect there.
• The cost is held from your balance at submission (batch rate), exactly as for hot jobs — insufficient balance is rejected synchronously with INSUFFICIENT_CREDIT.
• Batch is not guaranteed processing. If the job has not started when the 24-hour batch window ends, the default resolution is a rejection with a full refund: the job fails with error code BATCH_WINDOW_ELAPSED, nothing is charged, and you can resubmit hot (immediate) or batch again (same risk).
• Prefer never being rejected? Pass batch_fallback=hot: if the 24-hour window ends before the job starts, the job automatically switches to the hot lane and is billed at the hot rate — for a video, the hot price of the same render_mode and resolution (the price difference is charged when the switch happens; if your balance cannot cover it, the job falls back to the default rejection + full refund). An escalated job is a hot job from that point on: hot rate, hot result retention (24 hours).
• Batch results are retained 72 hours after completion (hot: 24 hours).
• Provide a callback_url to be notified on completion or rejection — signed with your API key's webhook secret, see Webhooks — or poll the status endpoint. A batch job still waiting can be cancelled for a full refund: see Cancel.

curl -X POST https://tonael.com/api/v1/sync \
  -H "X-API-Key: ton_your_api_key_here" \
  -F "audio=@song.mp3" \
  -F "lyrics=..." \
  -F "language=fr" \
  -F "priority=batch" \
  -F "batch_fallback=hot" \
  -F "callback_url=https://your-app.example.com/hooks/tonael"

Stem separation

Split a track into isolated stems. A separate product from alignment — billed on its own, per minute of source audio. No lyrics needed.

Karaoke video

Render an alignment you already have into a video. It takes the audio and the timings — not lyrics — so three formats of one song cost one alignment and three renders, not three of each.

Webhooks

We POST a JSON body to your callback_url when a job reaches a terminal state. Two kinds of job are pushed this way:

• Batch jobs (POST /api/v1/sync, /api/v1/stems, /api/v1/video and /api/v1/video/rerender with priority=batch), on completion or rejection — a job switched to hot by batch_fallback=hot included. Signed with your API key's webhook signing secret, video renders included.
• Hot karaoke video (POST /api/v1/video and POST /api/v1/video/rerender without priority=batch). Signed with the webhook_secret you sent with the request.

A hot /api/v1/sync job and a hot stem separation are not pushed: poll their status endpoints.

Delivery guarantees

• At-least-once delivery. A webhook may be delivered more than once. Deduplicate on job_id — treat a repeat of a job_id you have already processed as a no-op.
• Failed deliveries are retried with exponential backoff. Respond with a 2xx to acknowledge.

Your webhook signing secret

Each API key has its own. Find it in the console: API keys, then Webhook secret on the key's row. Rotate there replaces it: webhooks queued after the rotation are signed with the new secret, while a delivery already queued keeps the secret it was signed with, retries included. Hot video renders are the exception: they are signed with the webhook_secret you sent with the request, not with your key's secret. A batch video render is signed with your key's secret, like every other batch job.

Verifying the signature

Every delivery carries an X-Webhook-Signature header: the HMAC-SHA256 hex digest of the raw request body, keyed with the signing secret above. Compute it over the exact bytes you received, before parsing the JSON. We send canonical JSON — keys sorted alphabetically, UTF-8 encoded — but a body you parse and serialize again need not match those bytes, so never verify a re-serialized copy. Compare in constant time, and reject the delivery if the signature does not match.

import hashlib
import hmac

def verify(raw_body: bytes, signing_secret: str, received_signature: str) -> bool:
    expected = hmac.new(
        signing_secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, received_signature)

# Flask: verify(request.get_data(), SECRET, request.headers.get("X-Webhook-Signature", ""))

const express = require("express");
const crypto = require("crypto");

const app = express();
const SIGNING_SECRET = process.env.TONAEL_WEBHOOK_SECRET;

// express.raw keeps req.body as the exact bytes received (a Buffer).
app.post("/hooks/tonael", express.raw({ type: "application/json" }), (req, res) => {
  const expected = Buffer.from(
    crypto.createHmac("sha256", SIGNING_SECRET).update(req.body).digest("hex"),
  );
  const received = Buffer.from(req.get("X-Webhook-Signature") || "");
  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // Deduplicate on event.job_id, then handle the event.
  res.sendStatus(200);
});

Batch payload (completed)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "service_tier": "batch",
  "result_url": "https://tonael.com/api/v1/sync/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": "2026-04-05T10:30:12+00:00",
  "result": { "...": "the alignment GET /api/v1/sync/{job_id} returns" }
}

Batch payload (rejected or failed)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "error": {
    "code": "BATCH_WINDOW_ELAPSED",
    "message": "..."
  }
}

result_url is the status endpoint that serves the result. error.code is BATCH_WINDOW_ELAPSED when the 24-hour batch window elapsed (nothing is charged), or PROCESSING_FAILED. A video delivery carries a video object instead: video_url, the file's content_type, render_mode, dimensions and expires_at.

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",
  "checks": {
    "api": "ok",
    "database": "ok",
    "processing": "ok"
  }
}

Response 503 Service Unavailable (degraded)

{
  "status": "degraded",
  "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": "..."}}

Billing & Refunds

Supported Languages

Send the language of the lyrics as language. These 28 codes are accepted by both models; any other code is rejected with UNSUPPORTED_LANGUAGE.

Lyrics Guidelines

What you should do

What the API handles automatically

Limits