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

Generate an image

curl -X POST <your-api-url>/api/image/generate \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "<workflow-id>",
    "prompt": "walking through a rainy neon street",
    "provider": "<provider-id>",
    "width": 1024,
    "height": 1024
  }'

You get a prompt_id back. Generation is asynchronous — the job is queued and tracked.

Animate to video

One more call turns a still into motion using an image-to-video workflow. Pass the source image and a video workflow ID to POST /api/video/generate.

Name an action, not an atmosphere — an image-to-video model animates the pose in the start frame, so the clip should show an event someone could describe afterwards. Words like “slowly” and “gently” produce a near-still clip.

Run one action longer

An image-to-video clip runs about five seconds. For a single continuous action past that, use the wan22_i2v_context workflow and set length — it samples the whole clip in overlapping windows instead of generating separate takes, so the action carries through rather than restarting.

Chain into the next shot

Chaining is for a new shot — a different action, angle or place — not for making one action run longer, because each chained clip starts the model from a still.

POST /api/video/last-frame returns the final frame of a finished video as an image filename, which you pass as the image of the next shot, so the new shot starts on the frame the last one ended on. Name the clip by the prompt_id that made it, or by filename. The frame is cataloged like any upload, so you can edit it before animating it when the next shot needs a change motion alone can’t make.

POST /api/video/stitch joins finished clips into one video in playing order. Each is matched to the first clip’s frame size and frame rate, so shots that differ still join cleanly.

Give it a voice

POST /api/tts/generate speaks a line with ElevenLabs and returns an audio file. Pass that file as the audio of an InfiniteTalk video job and the person in the shot speaks it, lip-synced.

curl -X POST <your-api-url>/api/tts/generate \
  -H 'Content-Type: application/json' \
  -d '{"text": "You were supposed to wait for my signal."}'

Name a character to use the voice stored on it, or a voice_id from GET /api/tts/voices to pick one directly. This needs ELEVENLABS_API_KEY in your environment; without it the endpoint returns 503 and the rest of the API is unaffected.

Voice belongs at this stage rather than at final assembly: audio laid over a finished clip does not move the mouth.

Check on a job

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

Or browse recent work:

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

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.