Appearance
Topics
Every clip carries one topic. It is there so you can narrow a corpus of short videos down to what your learners actually care about, without building your own classifier over transcripts.
One label, from a fixed list
A clip has exactly one topic, chosen from eleven:
everyday · food · travel · sport · science · business · technology · entertainment · health · learning · other
The list is fixed on purpose. A free-text tag would drift, and a filter built on drifting tags breaks quietly. other is used when nothing else fits; it is a real answer, not a gap.
Unknown names are rejected rather than ignored, so topic=fodo returns a 400 instead of the whole corpus.
Assigned from the transcript
Topics come from the transcript at index time, not from channel names or YouTube categories. A cooking channel that posts a clip about buying a house gets business, not food.
Nothing here is hand-curated, so expect the odd clip to sit in a category you would have filed elsewhere. If a clip is clearly wrong, send us the clipId.
Topic and level are not independent
This is the part worth planning around. Across the English corpus:
| Topic | Clips | Share at A1-B1 |
|---|---|---|
| food | 151 | 90% |
| everyday | 47 | 81% |
| travel | 17 | 76% |
| learning | 47 | 70% |
| sport | 99 | 59% |
| entertainment | 124 | 58% |
| business | 62 | 34% |
| science | 202 | 28% |
| health | 54 | 28% |
Short videos about food and daily life carry short, concrete sentences; science and business carry abstraction. So a beginner-facing app gets more usable material by filtering on topic than by filtering on level alone, and an advanced app has the opposite pull.
Call /topics for the current counts, broken down by level, before you hard-code a topic into a lesson plan. The numbers move as the corpus grows:
bash
curl "https://clips.vocaflare.com/v1/topics" \
-H "Authorization: Bearer $CLIPS_API_KEY"Filtering
topic takes a comma separated list, on both the feed and word lookup:
bash
curl "https://clips.vocaflare.com/v1/feed?topic=food,everyday&level=A2" \
-H "Authorization: Bearer $CLIPS_API_KEY"
curl "https://clips.vocaflare.com/v1/words/receive/clips?topic=business" \
-H "Authorization: Bearer $CLIPS_API_KEY"Leave it out and nothing is filtered. Clips indexed before topics existed have no topic yet and drop out of a topic-filtered query; they still appear in unfiltered ones.