Skip to main content
POST

Authorizations

Authorization
string
header
required

Authorization: Bearer mm_live_…. Mint a key at mediamonster.app/keys; every plan includes the API. A test key, mm_test_…, runs every check a live key does and spends nothing: each run finishes at once with a stand-in file, and says livemode: false. A key does only what its scopes allow.

Headers

X-Request-Id
string

Your own id for this request — 8 to 128 letters, digits, ., _, : or -. Used in place of one we mint, and echoed back.

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$
Idempotency-Key
string

Retry this POST safely: the first request with a key runs and its answer is kept for a day; a retry with the same key and the same request gets that answer again, marked Idempotent-Replayed: true, instead of running twice. 1–255 printable characters — a UUID is a good one.

Required string length: 1 - 255

Query Parameters

dry_run
boolean
default:false

true to check and price the run without running it. Same as dry_run in the body.

Body

application/json

One file, and the steps to run on it: a recipe by name, or the steps themselves. Every step is checked before anything is charged.

url
string<uri>
upload_id
string<uuid>
job_id
string<uuid>
asset_id
string<uuid>
recipe
string

A ready-made recipe's slug, the id of one you saved on the Workbench, or the public slug of one somebody shared. A saved or shared one runs its latest version; add @ and a number (my-recipe@3) to run an earlier one.

recipe_id
string<uuid>

The id of a recipe you saved. Older than recipe, and takes only an id.

version
integer

Run this version of a saved or shared recipe, rather than its latest. The same as @3 on recipe; ready-made recipes have no versions.

Required range: x >= 1
steps
object[]
Minimum array length: 1
inputs
object

Values for the steps' {{names}}, like {"title": "Summer sale"}. A required input with no default has to be sent; a name the steps don't use is refused. describe_recipe, or GET /api/v1/recipes/{ref}, lists them under inputs. In a multipart form, send a JSON string or one field per input, inputs[title].

output
object

Save as, applied to the finished file: {"format": "webp", "quality": "85"}. Or a list of up to 5, one file each, all made from the last step's file: [{"format": "png"}, {"format": "webp"}]. In a list, format takes png, jpeg or webp. An entry that changes nothing on the finished file makes no file. The extra files are free.

wait
boolean
default:true
webhook_url
string<uri>
save_to_vault

true to file the results in the Vault, or {"folder": "Clients/Acme"} to say where.

dry_run
boolean
default:false

Check everything and answer with the price instead of running. Also taken as ?dry_run=true.

Response

The run finished while the call waited — or, with dry_run, what it would cost.

A recipe run: its steps in order, each with its state, and the finished files under outputs once every step is done.

id
string<uuid>
required
status
enum<string>
required
Available options:
queued,
processing,
complete,
failed
steps
object[]
required
poll_url
string
required
Example:

"/api/v1/runs/9a1d…"

name
string | null
recipe
object | null

The recipe the steps came from, and which version of it ran. Null for steps sent inline.

progress
object
facts
object

What analysis steps worked out, by name.

notes
object[]
shots
any[]
moments
any[]
outputs
object[]
credits_charged
integer
error
string | null
created_at
string<date-time>
updated_at
string<date-time>
vault
object

What save_to_vault filed. A run still going when the call came back says how to file it once it is done.

livemode
boolean

False for a test key's (mm_test_…) run, which charged nothing and ran nothing.

test
any

Present, and true, only on a test key's run.