Use the Speak AI MCP server tool apply_label to apply one or more labels to a span
of words in a media file’s transcript.
What does it do?
Apply one or more labels to a span of words in a media file’s transcript. Give the
span as quote (words copied from get_transcript; this tool finds their position
and the current transcriptRevision for you) or as range plus
expectedTranscriptRevision. If the same span already has labels, the new ones are
added to it. Check the returned anchor.exact to confirm the right words were
labelled. A 409 that says the transcript changed means someone edited it after your
revision was read: read the transcript again (get_transcript) and retry with the
new range or quote. Nothing was saved. A 400 means the range is outside the
transcript or a label is archived, a group, or not in this workspace. Requires the
labels assign permission (every member by default). The change is recorded in your
Speak Notifications under Label (type label).
Parameters
apply_label takes 6 parameters, 2 of them required.
| Name | Type | Required | Description |
|---|---|---|---|
mediaId |
string | Yes | Media id |
labelIds |
array of string | Yes | 1 to 20 distinct ids of active labels (not groups), from list_labels |
range |
object | No | Exact word range. Needs expectedTranscriptRevision. Prefer quote unless you already hold word indices. Word indices count the words of get_transcript’s insight.transcript in order, from 0: for each sentence, the words of its entities[].text when it has entities, otherwise its text split on spaces; tokens that are only punctuation are not counted. |
expectedTranscriptRevision |
number | No | transcriptRevision the range was read at (returned by get_transcript, list_media_labels and list_media_comments). Required with range. Optional with quote: the quote is found in the current transcript, and a revision you pass makes the call fail with 409 if the transcript changed since you read it. |
quote |
string | No | Words copied from the transcript, used instead of range. Matching ignores case and leading or trailing punctuation, and must cover whole words in order. If the words appear more than once, pass occurrence. |
occurrence |
number | No | Which match of quote to use (1 = first) when the quote appears more than once |
Behaviour
The Speak AI MCP server publishes these behaviour hints for apply_label.
- Can change data in your workspace.
- Does not delete or overwrite existing data.
- Repeating an identical call can have an extra effect.
- Stays inside Speak AI. Does not reach other systems.
Related
- Labels & comments lists the rest of the Labels & comments category.
- Tool reference lists every Speak AI MCP server tool.
- MCP server covers setup, supported clients, and what agents can do once connected.