Partner integration guide

Synced lyrics for every song in your catalog — one REST integration.

Two composable halves. The data half serves any platform: submit a song, we transcribe and time-align it in the original script, someone checks the words — on our pages or inside your product — and the outputs come back as LRC, SRT and word-level data. The optional layer on top: your users create lyric videos under your brand, paid by you or by them.

Three ways partners use this

Find yourself first — everything below serves all three

Catalog enrichment
Asset-management, sync & licensing platforms
Bulk-transcribe a catalog keyed by isrc and store lyrics, romanisation, translation and word timings as searchable metadata in your own product. Review happens in your UI — or not at all. Batches of 20 per call; limits raised for backfills.
Later, the same jobs can power self-serve video creation for your users — no re-integration.
Distribution & artist services
Distributors and labels
The full journey: artists check their own lyrics on branded pages, download LRC and SRT, and order lyric videos — white-label, with prepaid, monthly-settled or artist-pays commercials.
The worked example this page walks through step by step below.
In-product lyric features
Music apps and creator tools
The API as a feature engine: synced and karaoke-style lyrics in your own player or editor, corrections through the "api" review door, word-level JSON to render however you like.
Add video creation for your users whenever it earns its place.
The journey at a glance

Five steps, two of them optional

  1. 1Submit a songOne POST /v1/transcribe with the audio, the artist’s reference, and how you want review to run. Batches of up to 20 via POST /v1/batch.
  2. 2We transcribe and alignOriginal script, romanisation and translation, then line and word timing against the recording. Most songs finish in under a minute; a second, independent listener flags lines it heard differently.
  3. 3Someone checks the words (optional)Submit with review=true and the job holds until a human approves it — the artist on our hosted review page, or your own catalog team inside your product. Corrections feed the timing pass.
  4. 4Outputs deliveredA signed webhook tells you the moment a job lands; LRC, SRT and word-level JSON download per script. Poll instead if you prefer.
  5. 5Your user orders a lyric video (optional layer)From the same page they reviewed on: full-song 16:9, a 9:16 vertical, and a short teaser cut. Paid from your prepaid balance, or by your user directly with a commission accruing to you. Partners who only want the data never touch this step.
Before you write code

What we set up for you

Onboarding is a short call, not a signup form. We provision your organisation and hand over four things:

API key + webhook secret
Shown once, sent securely. The key authenticates every request; the secret signs every webhook we send you.
Your price book and settlement mode
Which products your end users see and at what price, in your currency — relevant only when you enable the self-serve layer — and whether you prepay us, settle monthly against metered usage, or let your users pay on-site with a commission to you.
Branding
End-user-facing pages start as lyrcs.ai; flip to white-label and your users see only your name. Data-only integrations can skip this entirely.
Rights attestation
Your agreement covers the content you submit — you confirm you hold the rights to have it transcribed and rendered.
Submitting songs

One call carries everything

Audio arrives as a direct file upload or an HTTPS audio_url(the only option above 4.5 MB; supported up to 100 MB). We only send GET requests, so presigned S3 and GCS links work, and a link its host refuses is rejected at submission before anything is charged. The link must stay valid until we fetch it — a minute or two for one song, longer when you submit in bulk and songs wait their turn, so make bulk links valid for 24 hours. After that we keep our own copy. Send an Idempotency-Key header and a retried submission can never create a second job or a second charge.

curl -X POST https://lyrcs.ai/api/v1/transcribe \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -H "Idempotency-Key: rv-88121-lyrics-1" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.example.com/masters/rv-88121.wav",
    "language": "hindi",
    "isrc": "INWAV2600347",          // dedupe + reporting
    "end_user": {                     // who the song belongs to
      "external_id": "rv-88121",     // your customer id — required
      "email": "artist@example.com", // optional, notifications only
      "name": "Ritika Verma"
    },
    "review": true,                   // hold for the artist's approval
    "review_delivery": "both",        // "both" | "link" | "api"
    "webhook_url": "https://api.example.com/hooks/lyrcs"
  }'

isrc is normalised and indexed — GET /v1/jobs?isrc=…answers “have we already done this song?” before you submit it twice. end_user.external_idis your customer reference and is what the artist’s whole downstream experience hangs off; the email is never used to match accounts. Every field is specified in the API reference.

The review, two ways

You choose where the words get checked

A held job is one job with two doors, chosen per submission with review_delivery. Both doors edit and approve the same lyrics; nothing downstream cares which one was used.

Door A — our hosted page (“link”)

The job.awaiting_review webhook carries an artist_url — a private link you forward to the artist, or whoever owns the song. No account, no password: the link holds a session that keeps working for 30 days of use. The page plays the audio line by line, takes edits, and follows your branding when white-label is on.

Door B — inside your product (“api”)

Read the held lyrics as lines from GET /v1/jobs/{id}, render them in your own UI — your fonts, your layout — and send corrections with the approval to POST /v1/jobs/{id}/approve. Choosing "api" means no link is ever minted, structurally. For catalog platforms this is usually the only door in use.

Webhooks you can trust

Signed, retried, and never silently lost

Five events: job.awaiting_review, job.complete, job.failed, job.degraded and batch.complete. Every delivery is HMAC-signed with your webhook secret; verify before trusting.

Failed deliveries retry 4 times. If your endpoint is down longer, the exact payload is kept in a dead-letter store: list with GET /v1/webhooks/dead-letters, resend the stored bytes with POST /v1/webhooks/dead-letters/{id}/replay — so an outage on your side never loses an event. Test your handler any time with POST /v1/webhook-test.

// headers on every delivery
X-Lyrcs-Event:     job.complete
X-Lyrcs-Job-Id:    9f3a…
X-Lyrcs-Timestamp: 1788500000
X-Lyrcs-Signature: sha256=hex(
  HMAC-SHA256(webhook_secret, raw_body)
)
The self-serve layer, under your brand

Let your users create lyric videos

Optional, and off until you switch it on: it exists only when a job carries an end_user and your price book offers products. Every such job gives that person — an artist, a label client, a sync manager — a private page listing their songs: review links, synced-lyric downloads (LRC and SRT, original or romanised), and lyric video ordering with a full studio: their artwork or ours, their styling, karaoke or static, full-song 16:9, a 9:16 vertical, and a short teaser cut for Reels and Shorts. White-label means they see your name on every one of these pages. Enabling it later needs no re-integration — the end_userreference you’ve been sending from day one is the hook it hangs on.

Prepaid
You hold a credit balance with us; your users' orders draw it down. They pay you (or nothing), outside our system.
Monthly settlement
For lyrics at volume: every API call is metered against your organisation, invoiced monthly.
Your user pays on-site
They check out on the order page itself; your commission accrues per order and is paid out against a monthly statement.

Prices and shares are set per agreement, in your currency — there is no public rate card. Default API limits (10 submissions a minute, 1,000 a day) suit a pilot and are raised per organisation when volume calls for it.

Go-live checklist
  • Store the API key and webhook secret server-side — the key is shown once.
  • Send isrc and end_user.external_id on every submission from day one; retrofitting references is painful.
  • Verify the webhook signature, respond 2xx fast, and wire a daily dead-letter check.
  • Pick your review door(s) per song with review_delivery — you can mix them freely.
  • Run one real song end to end — submit, review, approve, download — before pointing production traffic at us.
  • Decide branding (lyrcs.ai or white-label) before the first end user sees a review link.
  • Integrating for catalog data only? Skip branding and the price book — nothing end-user-facing exists until you add them.
Read the full API reference →Start an integration conversation