Skip to main content
POST
transcribe media

Authorizations

Authorization
string
header
required

An API key (es_live_…) from Settings, under API keys, or an OAuth access token.

Headers

Idempotency-Key
string

Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.

x-workspace-id
string

The workspace this one call acts in, when it is not the default: for a key or a connected agent, one of the workspaces the user allowed it.

Body

application/json
ref
string

An item ref, item id, or the job id that made it.

refs
string[]

Up to 20 audio or video items: their stored words, free; one that cannot be read is its own row.

Required array length: 1 - 20 elements
timeline_id
string

Transcribe the uploaded clips on this timeline that have no words yet, and give them the words.

clip_ids
string[]

With timeline_id: only these clips, read and charged again even if they have words, the way back from a transcript speech recognition got wrong.

include_words
boolean

ref: word-level timing as well as sentences.

format
enum<string>

sentences (default): each with start and end. lines: one timed line per sentence as one string, half the size, for reading a long file whole. phrases: speech broken at pauses, each with the gap after it, for choosing cut points. states, with refs: where each file's words stand, no words.

Available options:
sentences,
lines,
phrases,
states
start_time
number

ref: return only from this second. The whole file is still read.

Required range: x >= 0
end_time
number

ref: return only up to this second.

Required range: x >= 0
min_gap_ms
integer

format phrases: a pause this long or longer breaks one phrase from the next. Default 400; 700 and up finds only the breaths between takes.

Required range: 0 <= x <= 10000
speakers
boolean

format phrases: name who is talking on each phrase, from the voices the speakers tool picked out. A file nobody has been picked out of has none; this never listens to find out.

window
object

Only the speech touching this span of the file, in seconds. Lines stop at about 100,000 characters, an hour of speech or more, and next_start names where the next window begins.

context
string

Optional: one sentence shown to the user beside this action.

Maximum string length: 600

Response

Done, or a job started for work that runs longer (follow it with get_jobs).

ok
any
required
data
object
required
meta
object
required
media
object[]