Clip metadata

GET/v1/clips/{clipId}

Returns one clip. Accepts either the VocaFlare clip id (UUID) or the YouTube video id, so a caller that only stored the video id does not need a second lookup table.

Parameters

Name	In	Type	Default	Required	Description
clipId	path	string		yes	VocaFlare clip id (UUID) or the YouTube video id.
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.

Response

Field	Type	Description
clipId	string (uuid)	Stable VocaFlare id for the clip.
videoId	string	YouTube video id, for the embed.
title	string
language	string
level	A1 | A2 | B1 | B2 | C1 | C2	CEFR level assigned during screening.
topic	everyday | food | travel | sport | science | business | technology | entertainment | health | learning | other	What the clip is about. One label per clip, chosen from a fixed list so filters stay stable; other is used when nothing else fits. Topic and level are not independent: food, everyday and travel skew to the easier levels, science and business to the harder ones.
durationS	integer	Clip length in seconds. The corpus holds clips up to 180 s.
channel	object
channel.id	string	Source channel id.
channel.name	string	Channel name, for the attribution line.
embedUrl	string	Ready-to-use embed URL. Playback happens in the caller's player.
watchUrl	string	Canonical watch URL, for the required attribution link.
wordCount	integer	Catalogue words indexed in this clip.
indexedAt	string (ISO 8601)

Errors

Status	Code	When
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/clips/FinOIdu21XA \
  -H "Authorization: Bearer $VOCAFLARE_API_KEY"

{
  "clipId": "0f2a6c1e-88d7-4f0a-9f0b-1b7a2c3d4e5f",
  "videoId": "FinOIdu21XA",
  "title": "How to sound natural when you say 'receive'",
  "language": "en",
  "level": "B1",
  "topic": "learning",
  "durationS": 47,
  "wordCount": 38,
  "channel": {
    "id": "UCxxxxxxxxxxxxxxxxxxxxxx",
    "name": "BBC Learning English"
  },
  "embedUrl": "https://www.youtube.com/embed/FinOIdu21XA?playsinline=1",
  "watchUrl": "https://www.youtube.com/watch?v=FinOIdu21XA",
  "indexedAt": "2026-09-04T17:12:03Z"
}