Clips API

Appearance

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

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

2. Look up a word ​

bash
curl "https://clips.vocaflare.com/v1/words/receive/clips?gloss=tr&limit=5" \
  -H "Authorization: Bearer $VOCAFLARE_API_KEY"
json
{
  "matchedWord": "receive",
  "matchType": "exact",
  "clips": [
    {
      "clipId": "0f2a6c1e-88d7-4f0a-9f0b-1b7a2c3d4e5f",
      "videoId": "FinOIdu21XA",
      "level": "B1",
      "topic": "learning",
      "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.

html
<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 ​

bash
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 ​