Skip to main content
POST
inspect 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

A library item ref. One of ref, refs or urls.

refs
string[]

Up to 12 library item refs, read in one call. Every ref gets the same mode, window and at. One that cannot be read comes back as { ref, error } beside the rest rather than failing the call.

Required array length: 1 - 12 elements
urls
string<uri>[]

Up to 12 web addresses of pictures or videos, read without keeping them: the media a pull returned, say. The same modes as refs; twelve in all with refs. One that cannot be read comes back as { url, error }.

Required array length: 1 - 12 elements
mode
enum<string>

Video only. overview = whole-video storyboard grid (default); window = zoom into a span; frame = one exact moment; strip = one span (up to 60 s) as frames, waveform and words in one picture.

Available options:
overview,
window,
frame,
strip,
shot_log
window
object

window and strip modes: {start, end} in seconds.

at
number

frame mode: timestamp in seconds.

Required range: x >= 0
grid
boolean

An image or a single video frame (frame mode) comes back ruled in tenths, 0 to 1 each way, so a point read off it is the x and y that edit_points on generate_image and generate_video take.

cuts
boolean

Video only: every shot change and shot length. Free once the video is indexed; otherwise the file is read through on cloud processing.

prompt
string

A question for a model to answer about one video or audio file: motion, sound, timing, how type enters, when a thing happens. The answer comes back with the moments it rests on as seconds. Not for stills; one ref or url with it.

Required string length: 1 - 4000

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