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 key's own.

Body

application/json
ref
string

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

url
string<uri>
refs
string[]

Up to 20 audio or video items: their stored words, free. One that cannot be read comes back as its own row beside the rest.

Required array length: 1 - 20 elements
timeline_id
string

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

clip_ids
string[]

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

include_words
boolean

ref or url: 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.

Available options:
sentences,
lines,
phrases
start_time
number

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

Required range: x >= 0
end_time
number

ref or url: 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

format phrases: only phrases touching this span of the file, in seconds.

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[]