Quickstart

Three calls cover most integrations: find clips for a word, read the transcript, play the clip.

1. Check the corpus

/corpus needs no key. It tells you which languages are indexed and how much of the vocabulary has clips, which is the honest answer to "will this work for my users".

curl https://clips.vocaflare.com/v1/corpus

2. Look up a word

curl "https://clips.vocaflare.com/v1/words/receive/clips?gloss=tr&limit=5" \
  -H "Authorization: Bearer $VOCAFLARE_API_KEY"

{
  "matchedWord": "receive",
  "matchType": "exact",
  "clips": [
    {
      "clipId": "0f2a6c1e-88d7-4f0a-9f0b-1b7a2c3d4e5f",
      "videoId": "FinOIdu21XA",
      "level": "B1",
      "durationS": 47,
      "embedUrl": "https://www.youtube.com/embed/FinOIdu21XA?playsinline=1",
      "occurrences": [{ "tStart": 12.34, "captionIdx": 7, "text": "you receive the confirmation email" }]
    }
  ]
}

occurrences[0].tStart is the whole point: it is where the word is spoken.

3. Play from that second

Append the start time to the embed URL and let the platform player do the work.

<iframe
  src="https://www.youtube.com/embed/FinOIdu21XA?start=12&playsinline=1"
  allow="autoplay; encrypted-media"
  allowfullscreen
></iframe>

Round tStart down when you pass it as start: the parameter takes whole seconds, and landing a fraction early keeps the first phoneme of the word.

4. Add the transcript

curl "https://clips.vocaflare.com/v1/clips/FinOIdu21XA/transcript" \
  -H "Authorization: Bearer $VOCAFLARE_API_KEY"

Cues arrive in order with t0 and t1. Poll the player clock a few times a second and highlight the cue whose range contains it. That is the entire karaoke-caption feature.

Next

• Authentication before you ship a key anywhere.
• Word matching if your users type the word themselves.
• Playback and attribution for what you owe the source platform.