Agent API

Everything FlixML does is a REST call. Agents and humans use the same API. This page is a map — the authoritative, always-current reference is the live OpenAPI schema your install serves at /openapi.json, with GET /api/workflows/{id} for one workflow’s params in full.

If your agent runs in an MCP host such as Claude Desktop, Claude Code or Cursor, the MCP Server exposes all of this as tools and there is no API for it to learn.

Authenticate

Send your API key on every request as Authorization: Bearer <key>. The examples below leave it out. Each agent should get its own key; see API Keys & Access.

Discover first

Never hard-code IDs. Ask the running instance what it has:

curl <your-api-url>/api/workflows     # available workflows + their IDs
curl <your-api-url>/api/providers     # configured GPU providers
curl <your-api-url>/openapi.json      # full machine-readable schema

What /api/workflows returns

A list, one entry per workflow:

Field	What it is
id	Pass this as workflow when you generate.
name, description, task	What the workflow does.
output_type	image or video.
source	shipped with FlixML, or local to your install.
requirements	VRAM and model family it needs.
compatible_providers	Where it can run.
example	A sample request body, showing which fields to send. The prompt is a placeholder: write your own, don’t reuse it. null on workflows that don’t have one yet.
run_time	Median, min and max seconds per provider, from past runs.
details	Path to this workflow’s params: every input it accepts.

Params are the inputs a workflow takes: prompt, size, seed, steps and so on. The list leaves them out to stay short. Once you’ve picked a workflow, GET /api/workflows/{id} returns them, and each one says its type, whether it’s required, its default, and what it changes. Every shipped workflow’s params are also in the docs: see Params reference under Workflows, e.g. SDXL Base.

Generate

Making images and video has its own pages: Images and Videos.

Check on a job

curl <your-api-url>/api/jobs/<prompt_id>

Stop one your key queued. It leaves the queue if it is waiting and the GPU if it is running, and reads back as failed with error Cancelled:

curl -X POST <your-api-url>/api/jobs/<prompt_id>/cancel

Or browse recent work:

curl "<your-api-url>/api/listing?limit=5&sort=created_at&order=desc"

A finished job lists its outputs, each with a type and a url: image, video, audio, or file for anything else the workflow wrote, such as an FBX or GLB. Files don’t appear in the gallery; download them from the job, or from the button on its card in Studio.

Share work with another account

Send share_with with a generate request to share the job’s outputs, or set it on something that already exists. It replaces the list; [] unshares:

curl -X PATCH <your-api-url>/api/media/<filename>/metadata \
  -H "Content-Type: application/json" \
  -d '{"share_with": ["<account id>"]}'

It covers every output of the job. Those accounts see it in their gallery and download it with their own key. They can’t change, delete or re-share it.

What else the API covers

• Projects, Scenes, Shots — organize and render multi-shot films
• Characters — register and reference persistent identities
• LoRA training — datasets, training jobs, checkpoints
• Voice — ElevenLabs speech, lip-synced into a shot

For every endpoint, parameter, and payload shape, read your install’s /openapi.json. SKILL.md in the repo is the short guide an agent reads first: how to pick a workflow and run it.