Clips that contain a word

GET/v1/words/{word}/clips

Returns the clips whose transcript contains word, each with the timestamp where the word is spoken. This is the primary endpoint of the API.

The lookup is tolerant: the input is normalised (lowercased, accents folded), then matched against the catalogue, then against inflected forms (running matches run), then by trigram similarity (recieve matches receive). The word that was actually used is always returned in matchedWord, so a caller can show it back to the user.

Parameters

Name	In	Type	Default	Required	Description
word	path	string		yes	The word to look up. Case and accents are folded before matching.
language	query	string	en	no	Language of the clips, as a two-letter code. Only languages listed by /corpus return results.
gloss	query	en | es | ja | pt | ru | tr | zh	en	no	Language for word meanings in the response. Falls back to English when a meaning is missing in the requested language.
level	query	string		no	Restrict to these CEFR levels, comma separated. Omit for all levels.
match	query	strict | forms | fuzzy	fuzzy	no	How hard to try when the word is not in the catalogue. strict matches the exact form only, forms also accepts inflections, fuzzy also accepts near spellings.
order	query	recent | random	recent	no	recent returns the newest clips first and pages with cursor. random samples the word's clips instead, which is what you want when showing a handful on a page and not always the same handful; it ignores cursor and returns nextCursor: null.
limit	query	integer	20	no	Items per page.
cursor	query	string		no	The nextCursor of the previous page. Opaque; do not construct it yourself.

Response

Field	Type	Description
query	string	The word as it was sent.
matchedWord	string	The catalogue word the results are for. Differs from query after a form or fuzzy match.
matchType	exact | forms | fuzzy
didYouMean	string[]	Other close candidates, best first. Empty on an exact match.
word	object
word.word	string
word.wordId	integer
word.level	A1 | A2 | B1 | B2 | C1 | C2	CEFR level assigned during screening.
word.meaning	string	Meaning in the requested gloss language.
word.clipCount	integer
clips	object[]
clips[].clipId	string (uuid)	Stable Vocaflare id for the clip.
clips[].videoId	string	YouTube video id, for the embed.
clips[].title	string
clips[].language	string
clips[].level	A1 | A2 | B1 | B2 | C1 | C2	CEFR level assigned during screening.
clips[].durationS	integer	Clip length in seconds. The corpus holds clips up to 180 s.
clips[].channel	object
clips[].channel.id	string	Source channel id.
clips[].channel.name	string	Channel name, for the attribution line.
clips[].embedUrl	string	Ready-to-use embed URL. Playback happens in the caller's player.
clips[].watchUrl	string	Canonical watch URL, for the required attribution link.
clips[].occurrences	object[]	Where the word is spoken in this clip. The index currently stores the first occurrence per clip, so this array holds one item; it is an array because later index versions will list repeats without a breaking change.
clips[].occurrences[].tStart	number	Seconds from the start of the clip. Seek here to hear the word.
clips[].occurrences[].captionIdx	integer	Index of the cue that contains the word, matching /transcript.
clips[].occurrences[].text	string	The cue text, so a result list can show context without a second call.
totalCount	integer
nextCursor	string

Errors

Status	Code	When
400	invalid_request	A parameter is missing or malformed.
401	invalid_key	The key is missing, unknown or disabled.
404	not_found	No such clip, or the word is not in the catalogue.
429	rate_limited	Too many requests, or the plan quota is spent. Retry-After carries the wait in seconds.

Example

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

{
  "query": "recieve",
  "matchedWord": "receive",
  "matchType": "fuzzy",
  "didYouMean": [
    "receive",
    "relieve"
  ],
  "word": {
    "word": "receive",
    "wordId": 4127,
    "level": "B1",
    "meaning": "almak",
    "clipCount": 9
  },
  "clips": [
    {
      "clipId": "0f2a6c1e-88d7-4f0a-9f0b-1b7a2c3d4e5f",
      "videoId": "FinOIdu21XA",
      "title": "How to sound natural when you say 'receive'",
      "language": "en",
      "level": "B1",
      "durationS": 47,
      "channel": {
        "id": "UCxxxxxxxxxxxxxxxxxxxxxx",
        "name": "BBC Learning English"
      },
      "embedUrl": "https://www.youtube.com/embed/FinOIdu21XA?playsinline=1",
      "watchUrl": "https://www.youtube.com/watch?v=FinOIdu21XA",
      "occurrences": [
        {
          "tStart": 12.34,
          "captionIdx": 7,
          "text": "you receive the confirmation email"
        }
      ]
    }
  ],
  "totalCount": 9,
  "nextCursor": null
}