MediaRuntime Jobs API
Create, list, and inspect asynchronous media jobs.
Create, list, and inspect asynchronous media jobs.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/mediaruntime-jobs-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
description: Asynchronous media processing for video, audio, and images.
title: MediaRuntime Jobs API
version: 1.0.0
servers:
- description: Production
url: https://mediaruntime.com
tags:
- description: Create, list, and inspect asynchronous media jobs.
name: Jobs
paths:
/v1/jobs:
get:
description: Lists the caller's jobs newest first, with optional status filtering and cursor pagination. Fetch a single job to obtain its current bundle link.
operationId: listJobs
parameters:
- description: Filter by status, e.g. COMPLETED, FAILED, PROCESSING
in: query
name: status
required: false
schema:
default: ''
description: Filter by status, e.g. COMPLETED, FAILED, PROCESSING
title: Status
type: string
- description: Rows per page (max 100)
in: query
name: limit
required: false
schema:
default: 25
description: Rows per page (max 100)
maximum: 100
minimum: 1
title: Limit
type: integer
- description: job_id from a previous page's next_cursor
in: query
name: cursor
required: false
schema:
default: ''
description: job_id from a previous page's next_cursor
title: Cursor
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/JobListResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- ProductionApiKey: []
summary: List jobs
tags:
- Jobs
post:
description: Creates an asynchronous media-processing job. Authenticate with a production API key or an ephemeral sandbox token. Sandbox jobs support only capabilities marked for the sandbox environment. Use Idempotency-Key when safely retrying the same logical request.
operationId: createJob
parameters:
- description: Optional. Retrying with the same key returns the original job instead of queueing (and charging for) a second one. Scoped to your account, honoured for 24 hours.
in: header
name: Idempotency-Key
required: false
schema:
default: ''
description: Optional. Retrying with the same key returns the original job instead of queueing (and charging for) a second one. Scoped to your account, honoured for 24 hours.
title: Idempotency-Key
type: string
requestBody:
content:
application/json:
examples:
batch:
summary: Apply one output recipe to two inputs
value:
inputs:
- input_id: asset-a
source: https://cdn.example.com/media/a.mp4
- input_id: asset-b
source: https://cdn.example.com/media/b.mp4
outputs:
- video.web
multipleOutputs:
summary: Create streaming video, a transcript, and a media report
value:
outputs:
- video.streaming
- audio.transcription
- preset: media_report_v1
type: image
source: https://cdn.example.com/media/launch.mp4
webVideo:
summary: Create one web-ready video
value:
outputs:
- video.web
source: https://cdn.example.com/media/launch.mp4
schema:
$ref: '#/components/schemas/CreateJobRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- ProductionApiKey: []
- SandboxToken: []
summary: Create a media job
tags:
- Jobs
/v1/jobs/{job_id}:
get:
description: Returns the current status, tier decision, usage, billing, probed input media, caller metadata, and expiring bundle access for one owned job.
operationId: getJob
parameters:
- description: The ID of the job to inspect
in: path
name: job_id
required: true
schema:
description: The ID of the job to inspect
title: Job Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- ProductionApiKey: []
summary: Get a job
tags:
- Jobs
components:
schemas:
JobMediaStreamCounts:
properties:
audio:
default: 0
title: Audio
type: integer
other:
default: 0
description: Subtitle, data and attachment streams
title: Other
type: integer
video:
default: 0
title: Video
type: integer
title: JobMediaStreamCounts
type: object
VideoOptions:
properties:
bitrate_bps:
default: 0
maximum: 2000000000.0
minimum: 0.0
title: Bitrate Bps
type: integer
codec:
anyOf:
- maxLength: 32
type: string
- type: 'null'
description: h264, hevc, av1, vp9
title: Codec
fps:
default: 0.0
maximum: 240.0
minimum: 0.0
title: Fps
type: number
height:
default: 0
maximum: 16384.0
minimum: 0.0
title: Height
type: integer
preset:
anyOf:
- maxLength: 64
type: string
- type: 'null'
description: fast, slow, etc.
title: Preset
two_pass:
default: false
title: Two Pass
type: boolean
title: VideoOptions
type: object
ContactSheetFormat:
enum:
- jpg
- png
- webp
title: ContactSheetFormat
type: string
GifPreviewConfig:
properties:
duration:
default: 5.0
exclusiveMinimum: 0.0
maximum: 600.0
title: Duration
type: number
enabled:
default: false
title: Enabled
type: boolean
fps:
default: 10.0
exclusiveMinimum: 0.0
maximum: 60.0
title: Fps
type: number
start_time:
default: 0.0
maximum: 604800.0
minimum: 0.0
title: Start Time
type: number
width:
default: 320
maximum: 4096.0
minimum: 1.0
title: Width
type: integer
title: GifPreviewConfig
type: object
ThumbnailConfig:
properties:
cols:
default: 5
maximum: 20.0
minimum: 1.0
title: Cols
type: integer
enabled:
default: false
title: Enabled
type: boolean
format:
$ref: '#/components/schemas/ImageFormat'
default: jpg
interval_sec:
default: 2.0
exclusiveMinimum: 0.0
maximum: 86400.0
title: Interval Sec
type: number
max_sheets:
default: 10
maximum: 100.0
minimum: 1.0
title: Max Sheets
type: integer
rows:
default: 5
maximum: 20.0
minimum: 1.0
title: Rows
type: integer
tile_height:
default: 90
maximum: 4096.0
minimum: 1.0
title: Tile Height
type: integer
tile_width:
default: 160
maximum: 4096.0
minimum: 1.0
title: Tile Width
type: integer
title: ThumbnailConfig
type: object
ContactSheetConfig:
properties:
columns:
default: 4
maximum: 10.0
minimum: 1.0
title: Columns
type: integer
duration_sec:
default: 0.0
description: Selected source duration; zero means the remaining video.
maximum: 21600.0
minimum: 0.0
title: Duration Sec
type: number
format:
$ref: '#/components/schemas/ContactSheetFormat'
default: jpg
interval_sec:
default: 10.0
maximum: 3600.0
minimum: 0.5
title: Interval Sec
type: number
max_sheets:
default: 4
maximum: 20.0
minimum: 1.0
title: Max Sheets
type: integer
quality:
default: 80
maximum: 100.0
minimum: 1.0
title: Quality
type: integer
rows:
default: 4
maximum: 10.0
minimum: 1.0
title: Rows
type: integer
start_time_sec:
default: 0.0
maximum: 604800.0
minimum: 0.0
title: Start Time Sec
type: number
tile_height:
default: 180
maximum: 640.0
minimum: 36.0
title: Tile Height
type: integer
tile_width:
default: 320
maximum: 640.0
minimum: 64.0
title: Tile Width
type: integer
title: ContactSheetConfig
type: object
ModerationConfig:
properties:
checks:
items:
$ref: '#/components/schemas/ModerationCheck'
maxItems: 3
minItems: 1
title: Checks
type: array
enabled:
default: false
title: Enabled
type: boolean
mode:
$ref: '#/components/schemas/ModerationMode'
default: report
title: ModerationConfig
type: object
ModerationMode:
enum:
- report
- block
title: ModerationMode
type: string
PrivacyFailureMode:
enum:
- fail_closed
- report_only
title: PrivacyFailureMode
type: string
JobBillingInfo:
properties:
currency:
anyOf:
- type: string
- type: 'null'
title: Currency
estimated_amount_cents:
anyOf:
- type: integer
- type: 'null'
title: Estimated Amount Cents
estimated_units:
anyOf:
- type: integer
- type: 'null'
title: Estimated Units
final_amount_cents:
anyOf:
- type: integer
- type: 'null'
title: Final Amount Cents
final_units:
anyOf:
- type: integer
- type: 'null'
title: Final Units
status:
anyOf:
- type: string
- type: 'null'
title: Status
unit_price_cents:
anyOf:
- type: integer
- type: 'null'
title: Unit Price Cents
title: JobBillingInfo
type: object
PrivacyDetector:
enum:
- face
- license_plate
- text
title: PrivacyDetector
type: string
JobMediaVideoInfo:
description: 'The primary video stream.
width/height are DISPLAY dimensions — rotation already applied. A phone clip shot
portrait is commonly encoded 1920x1080 with rotation_deg=90, and every consumer that
reads the encoded dimensions instead gets the orientation wrong. encoded_* is kept
alongside for the cases that genuinely need the pre-rotation values.'
properties:
bit_rate:
anyOf:
- type: integer
- type: 'null'
title: Bit Rate
codec:
anyOf:
- type: string
- type: 'null'
title: Codec
display_aspect_ratio:
anyOf:
- type: string
- type: 'null'
title: Display Aspect Ratio
encoded_height:
anyOf:
- type: integer
- type: 'null'
description: Height as stored, before rotation
title: Encoded Height
encoded_width:
anyOf:
- type: integer
- type: 'null'
description: Width as stored, before rotation
title: Encoded Width
fps:
anyOf:
- type: number
- type: 'null'
title: Fps
height:
anyOf:
- type: integer
- type: 'null'
description: Display height, after rotation
title: Height
is_rotated:
anyOf:
- type: boolean
- type: 'null'
title: Is Rotated
orientation:
anyOf:
- type: string
- type: 'null'
description: landscape, portrait or square
title: Orientation
profile:
anyOf:
- type: string
- type: 'null'
title: Profile
rotation_deg:
anyOf:
- type: integer
- type: 'null'
title: Rotation Deg
width:
anyOf:
- type: integer
- type: 'null'
description: Display width, after rotation
title: Width
title: JobMediaVideoInfo
type: object
JobStatusResponse:
properties:
billing:
$ref: '#/components/schemas/JobBillingInfo'
bundle:
$ref: '#/components/schemas/JobBundleInfo'
completed_at:
anyOf:
- type: string
- type: 'null'
title: Completed At
created_at:
anyOf:
- type: string
- type: 'null'
title: Created At
error:
anyOf:
- type: string
- type: 'null'
title: Error
job_id:
title: Job Id
type: string
media:
anyOf:
- $ref: '#/components/schemas/JobMediaInfo'
- type: 'null'
description: What the input was, as probed at submit. Null when no probe was stored.
metadata:
additionalProperties: true
description: The metadata you submitted
title: Metadata
type: object
recipe:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
description: Exact hosted recipe version materialized for this job, when used.
title: Recipe
started_at:
anyOf:
- type: string
- type: 'null'
title: Started At
status:
title: Status
type: string
tier:
$ref: '#/components/schemas/JobTierInfo'
updated_at:
anyOf:
- type: string
- type: 'null'
title: Updated At
usage:
$ref: '#/components/schemas/JobUsageInfo'
required:
- job_id
- status
- tier
- usage
- billing
- bundle
title: JobStatusResponse
type: object
AudiogramArtworkFit:
enum:
- contain
- cover
- blurred_background
title: AudiogramArtworkFit
type: string
WatermarkConfig:
properties:
enabled:
default: false
title: Enabled
type: boolean
title: WatermarkConfig
type: object
JobInput:
properties:
file_url:
anyOf:
- maxLength: 2048
minLength: 1
type: string
- type: 'null'
description: Permanent legacy spelling of source for one batch item.
title: File Url
input_id:
anyOf:
- maxLength: 128
type: string
- type: 'null'
description: Caller-supplied stable identifier for this input within a batch
title: Input Id
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
description: Opaque per-input metadata persisted with the child job and echoed in batch webhooks.
title: Metadata
source:
anyOf:
- maxLength: 2048
minLength: 1
type: string
- $ref: '#/components/schemas/SourceUrl'
- type: 'null'
description: 'Canonical batch input: an HTTP(S)/gs:// string or an object containing only a url field. Mutually exclusive with file_url.'
title: Source
title: JobInput
type: object
AudioOptions:
properties:
bitrate_bps:
default: 0
maximum: 10000000.0
minimum: 0.0
title: Bitrate Bps
type: integer
channels:
default: 0
maximum: 32.0
minimum: 0.0
title: Channels
type: integer
codec:
anyOf:
- maxLength: 32
type: string
- type: 'null'
description: aac, mp3, opus, ac3
title: Codec
title: AudioOptions
type: object
JobMediaAudioInfo:
description: The primary audio stream.
properties:
bit_rate:
anyOf:
- type: integer
- type: 'null'
title: Bit Rate
channels:
anyOf:
- type: integer
- type: 'null'
title: Channels
codec:
anyOf:
- type: string
- type: 'null'
title: Codec
layout:
anyOf:
- type: string
- type: 'null'
description: Channel layout, e.g. stereo or 5.1
title: Layout
profile:
anyOf:
- type: string
- type: 'null'
title: Profile
sample_rate_hz:
anyOf:
- type: integer
- type: 'null'
title: Sample Rate Hz
title: JobMediaAudioInfo
type: object
ImageRendition:
properties:
format:
$ref: '#/components/schemas/ImageFormat'
height:
maximum: 16384.0
minimum: 1.0
title: Height
type: integer
max_bytes:
anyOf:
- maximum: 100000000.0
minimum: 256.0
type: integer
- type: 'null'
description: Optional hard encoded-file ceiling for JPG/WebP. The job fails rather than returning an oversized rendition.
title: Max Bytes
min_quality:
default: 1
description: Lowest quality the bounded search may use when max_bytes is set.
maximum: 100.0
minimum: 1.0
title: Min Quality
type: integer
mode:
default: cover
maxLength: 32
minLength: 1
title: Mode
type: string
quality:
default: 80
maximum: 100.0
minimum: 1.0
title: Quality
type: integer
width:
maximum: 16384.0
minimum: 1.0
title: Width
type: integer
required:
- width
- height
- format
title: ImageRendition
type: object
AudiogramCaptionPosition:
enum:
- top
- bottom
title: AudiogramCaptionPosition
type: string
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
JobMediaInfo:
description: 'What the input actually was, as probed at submit.
This is the same probe the submit-time compatibility checks read, so it explains
rejections: an mp3 refused for an image output has no video stream here, and a still
refused for frames has no duration.
Every field is optional. The probe can be partial or absent — an unusual container, a
job submitted before this data was stored — and a missing field means "not reported",
never zero.'
properties:
audio:
anyOf:
- $ref: '#/components/schemas/JobMediaAudioInfo'
- type: 'null'
bit_rate:
anyOf:
- type: integer
- type: 'null'
description: Overall container bit rate, bits per second
title: Bit Rate
duration_sec:
anyOf:
- type: number
- type: 'null'
description: Absent for still images, which have no timeline.
title: Duration Sec
format:
anyOf:
- type: string
- type: 'null'
description: Container format reported by ffprobe
title: Format
streams:
$ref: '#/components/schemas/JobMediaStreamCounts'
video:
anyOf:
- $ref: '#/components/schemas/JobMediaVideoInfo'
- type: 'null'
title: JobMediaInfo
type: object
SourceUrl:
additionalProperties: false
description: The first extensible source object; other source kinds remain reserved.
properties:
url:
maxLength: 2048
minLength: 1
title: Url
type: string
required:
- url
title: SourceUrl
type: object
JobResponse:
properties:
job_id:
title: Job Id
type: string
msg:
title: Msg
type: string
outputs:
items:
additionalProperties: true
type: object
title: Outputs
type: array
recipe:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Recipe
required_tier:
anyOf:
- type: string
- type: 'null'
title: Required Tier
status:
title: Status
type: string
tier:
title: Tier
type: string
required:
- job_id
- status
- tier
- msg
title: JobResponse
type: object
CreateJobRequest:
description: 'Create one asynchronous media job. Choose exactly one input form: source, the legacy file_url field, or inputs for a batch. Choose either a hosted recipe or explicit processing options. Terminal events are sent to the account webhook destination configured in MediaRuntime.'
oneOf:
- not:
anyOf:
- required:
- file_url
- required:
- inputs
required:
- source
- not:
anyOf:
- required:
- source
- required:
- inputs
required:
- file_url
- not:
anyOf:
- required:
- source
- required:
- file_url
required:
- inputs
properties:
file_url:
anyOf:
- maxLength: 2048
minLength: 1
type: string
- type: 'null'
description: GCS URI (gs://) or Public HTTP URL
title: File Url
inputs:
anyOf:
- items:
$ref: '#/components/schemas/JobInput'
maxItems: 25
minItems: 1
type: array
- type: 'null'
description: Optional multi-input batch request. Use this instead of source/file_url for additive batch fan-out.
title: Inputs
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
description: Opaque caller metadata persisted with the job and echoed in completion webhooks.
title: Metadata
moderation:
anyOf:
- $ref: '#/components/schemas/ModerationConfig'
- type: 'null'
description: Optional premium moderation request for image or video inputs.
outputs:
description: Output recipes as explicit objects or frozen alias strings. May be empty ONLY for an analysis-only job — currently a job with moderation enabled, which produces a verdict and no media.
items:
anyOf:
- $ref: '#/components/schemas/TranscodeOutput'
- type: string
maxItems: 10
title: Outputs
type: array
recipe:
anyOf:
- maxLength: 80
minLength: 3
pattern: ^[a-z][a-z0-9-]{2,63}(?:@[1-9][0-9]*)?$
type: string
- type: 'null'
description: Hosted recipe reference, optionally pinned as name@version.
title: Recipe
source:
anyOf:
- maxLength: 2048
minLength: 1
type: string
- $ref: '#/components/schemas/SourceUrl'
- type: 'null'
description: 'Canonical single input: an HTTP(S)/gs:// string or an object containing only a url field. Mutually exclusive with file_url and inputs.'
title: Source
watermark:
anyOf:
- $ref: '#/components/schemas/WatermarkConfig'
- type: 'null'
description: Optional premium watermark request; overlays the account's logo onto every output.
title: CreateJobRequest
type: object
OutputType:
enum:
- mp4
- webm
- hls
- dash
- audio
- image
- social
- gif
- frames
title: OutputType
type: string
SubtitleConfig:
properties:
enabled:
default: false
title: Enabled
type: boolean
format:
$ref: '#/components/schemas/SubtitleFormat'
default: both
languages:
items:
type: string
maxItems: 10
minItems: 1
title: Languages
type: array
max_audio_minutes:
default: 0
maximum: 1440.0
minimum: 0.0
title: Max Audio Minutes
type: integer
model:
default: base
maxLength: 64
minLength: 1
title: Model
type: string
translate_to_english:
default: false
title: Translate To English
type: boolean
title: SubtitleConfig
type: object
JobTierInfo:
properties:
billed:
anyOf:
- type: string
- type: 'null'
description: Tier actually charged
title: Billed
effective:
anyOf:
- type: string
- type: 'null'
description: Tier the job executed on
title: Effective
reasons:
description: Why premium was required, if it was
items:
type: string
title: Reasons
type: array
requested:
anyOf:
- type: string
- type: 'null'
description: Tier of the API key that submitted the job
title: Requested
required:
anyOf:
- type: string
- type: 'null'
description: Tier the work actually needs
title: Required
title: JobTierInfo
type: object
PrivacyRedactionConfig:
additionalProperties: false
description: Explicit, bounded controls for automated visual privacy redaction.
properties:
box_padding_ratio:
default: 0.15
maximum: 0.5
minimum: 0.0
title: Box Padding Ratio
type: number
detectors:
items:
$ref: '#/components/schemas/PrivacyDetector'
maxItems: 3
minItems: 1
title: Detectors
type: array
failure_mode:
$ref: '#/components/schemas/PrivacyFailureMode'
default: fail_closed
include_debug_observations:
default: false
title: Include Debug Observations
type: boolean
max_frames:
default: 1800
maximum: 18000.0
minimum: 1.0
title: Max Frames
type: integer
min_confidence:
default: 0.6
maximum: 0.99
minimum: 0.3
title: Min Confidence
type: number
pixel_block_size:
default: 24
maximum: 128.0
minimum: 4.0
title: Pixel Block Size
type: integer
privacy_strength:
default: strong
enum:
- standard
- strong
title: Privacy Strength
type: string
sample_interval_sec:
default: 0.2
maximum: 30.0
minimum: 0.1
title: Sample Interval Sec
type: number
solid_color:
default: '#000000'
pattern: ^#[0-9A-Fa-f]{6}$
title: Solid Color
type: string
style:
$ref: '#/components/schemas/PrivacyRedactionStyle'
default: blur
required:
- detectors
title: PrivacyRedactionConfig
type: object
SubtitleFormat:
enum:
- srt
- vtt
- both
title: SubtitleFormat
type: string
AudiogramConfig:
additionalProperties: false
description: Bounded public controls for composing audio, artwork, and captions.
properties:
artwork_fit:
$ref: '#/components/schemas/AudiogramArtworkFit'
default: blurred_background
artwork_source:
maxLength: 2048
minLength: 1
title: Artwork Source
type: string
background_color:
default: '#101827'
pattern: ^#[0-9A-Fa-f]{6}$
title: Background Color
type: string
burn_captions:
default: false
title: Burn Captions
type: boolean
caption_font_scale:
default: 1.0
maximum: 1.5
minimum: 0.75
title: Caption Font Scale
type: number
caption_position:
$ref: '#/components/schemas/AudiogramCaptionPosition'
default: bottom
captions_source:
anyOf:
- maxLength: 2048
minLength: 1
type: string
- type: 'null'
title: Captions Source
duration_sec:
default: 60.0
exclusiveMinimum: 0.0
maximum: 300.0
title: Duration Sec
type: number
fps:
default: 30
maximum: 30.0
minimum: 15.0
title: Fps
type: integer
layout:
$ref: '#/components/schemas/AudiogramLayout'
default: square
loudness_target_lufs:
default: -16.0
maximum: -12.0
minimum: -24.0
title: Loudness Target Lufs
type: number
normalize_audio:
default: false
title: Normalize Audio
type: boolean
start_time_sec:
default: 0.0
maximum: 604800.0
minimum: 0.0
title: Start Time Sec
type: number
waveform_color:
default: '#5B5CFF'
pattern: ^#[0-9A-Fa-f]{6}$
title: Waveform Color
type: string
waveform_gain:
default: 2.0
maximum: 4.0
minimum: 0.5
title: Waveform Gain
type: number
required:
- artwork_source
title: AudiogramConfig
type: object
AnimationConfig:
properties:
duration:
default: 6.0
exclusiveMinimum: 0.0
maximum: 30.0
title: Duration
type: number
fps:
default: 15.0
exclusiveMinimum: 0.0
maximum: 30.0
title: Fps
type: number
loop:
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mediaruntime/refs/heads/main/openapi/mediaruntime-jobs-api-openapi.yml