Skip to main content
POST /api/v1/run/{skill} Run one skill. The slug is the same one the site uses — /api/v1/run/background-remover. Option ids come from GET /api/v1/skills. An option the skill doesn’t have is an error, not a default. Credits come off before the provider is called and go back if the run fails. The response includes credits_charged. Text results — alt text, transcripts — ride back inline rather than as a file.
Send an Idempotency-Key header to make a retry safe: a second request with the same key and the same body gets the first answer back instead of running again. See Idempotency.
A file sent in the request body — -F file=@… — stops at 100 MB a request, whatever the plan. Over that, Cloudflare answers with a 413 before the request reaches us. For anything bigger, send it as a direct upload and pass its upload_id, send a public url (fetched up to your plan’s ceiling), or upload it through the app and pass its job_id.
A skill flagged needs_reference edits with a second image. Today that is swap and virtual try-on. Those two have no Workbench page. Join into one, Merge PDFs, Pictures to PDF, and Lay them out as one need a set. POST /api/v1/run/{skill} and MCP take one file per request and refuse them with 400 nothing_to_join before the file is stored. On the Workbench their /skills/<slug> page takes the files you drop in as the set. To run one from your own code, put it under a set-making step on POST /api/v1/runs.

Dry runs

Send dry_run=true — in the body, as a form field, or on the URL — to find out what a run would cost without running it. It works on POST /api/v1/run/{skill}, POST /api/v1/runs and POST /api/v1/convert. A dry run makes every check the run would: the file is fetched, sniffed and measured, then thrown away; the options, the plan and the prompt are checked. Anything the run would refuse, the dry run refuses, with the same error. Otherwise it answers 200 with the price, worked out by the same code that charges it:
Nothing is charged, queued or stored. A dry run counts against your rate limit like any request.

Clips: a stretch, and a re-cut

Clips takes three options that aren’t in its option list, because no menu sets them: moments is what the Workbench writes when you move a clip’s edge or drop one. It is charged 12 per clip and nothing for listening. When Clips has already run on the same file, each edge is moved out to the whole word it falls in; otherwise it is cut exactly where you named it. Each clip keeps the title, score and reason of the pick it was cut from. A stretch that starts past the end of the video, a from after to, or a window under 15 seconds is refused with 400 bad_option before anything is charged. A moments or to that runs past the end is cut at the last frame. Every clip comes back with data describing it: title, score (0–100), reason, source (where in the video it came from) and, where the picture added something, seen. A video with too little said in it — sport, B-roll, a launch, a demo with the sound off — is watched rather than read: the moments are found in the picture, and seen says what happens in each. That is automatic, at the same price, for videos up to two hours.

Run on a Vault file

Send asset_id instead of file or url to run on a file already in the Vault. The bytes never leave storage, and the Vault file is left as it is: the run makes a new file.
Looking at a file is enough to run on it. A guest in a workspace can only use files in the folders they were given; any other id is 404 file_not_found, the same as an id that doesn’t exist.

Save results to the Vault

save_to_vault files what the run made in the Vault once it finishes. Send {} for no folder, or {"folder": "Clients/Acme"}. It works on POST /api/v1/run/{skill}, POST /api/v1/runs and POST /api/v1/convert. In a multipart form, send it as JSON text or true. If you can’t add files to that folder, the call is refused with 403 not_allowed before anything is charged. The response carries a vault object:
With wait=false, or a run still going when the call returns, vault says "pending": true. Store it later with POST /api/v1/assets and the job_id. To run several skills in sequence, use POST /api/v1/runs.