For developers & agents
Your agent can make films too.
The same image, video and voice models the app runs on, for any agent that speaks MCP and any terminal. One paste carries everything — both ways in, every tool, every price — and your agent picks its path, then proves the connection with a credits check. No API keys.
Give this to your agent.
Set yourself up to generate images, video and voiceovers with Flummox using the document below — it covers both ways in (hosted MCP connector and CLI), every tool and all pricing. Pick whichever path fits where you run, then confirm the connection by checking my credit balance.
---
# Flummox
Flummox generates AI video, image, and voiceover against a credits-based
account. This file is for an agent, not a person — terse and exact. For a
human, see https://www.flummox.ai/developers.
## Two ways in, plus a no-MCP fallback
No Flummox account yet? Don't send the user off to sign up first — both
paths below reach a sign-in page whose "Create one" link makes signup part
of the same flow (one Google click or email), and a new account starts
with free welcome credits. Just start the connection.
1. CLI + local MCP (stdio). Works in any shell, CI box, or agent sandbox
that can exec a binary.
npm i -g flummox-cli
flummox login # browser approval; prints a code + URL too,
# so it also works headless. No API keys —
# writes a token to ~/.config/flummox.
flummox mcp # runs an MCP server over stdio: 11 tools.
Any MCP client that launches subprocesses takes a command+args config:
{ "mcpServers": { "flummox": { "command": "flummox", "args": ["mcp"] } } }
2. Hosted remote MCP, no install: https://www.flummox.ai/api/mcp — a
streamable-HTTP MCP server behind OAuth. Point any remote-MCP client at
that URL; a spec-compliant client discovers the OAuth flow itself (RFC
9728 + 8414, dynamic client registration) and you sign in with a Flummox
account once. Serves 10 of the 11 tools below — no download_file, since
there is no local disk inside the server. A job's url is a plain HTTPS
file; fetch it yourself.
3. No MCP support at all: run the CLI directly. `flummox image/video/voice/
project/projects/models/credits/history/download` are plain shell
commands — parse stdout, check the exit code (0 ok, 2 payment required,
1 everything else).
## Tools — name, args, returns
generate_image(prompt: string required, model?: id from list_models,
ratio?: e.g. "16:9", project_id?: uuid, defaults to newest project) ->
{job_id: "image/<id>", credits, balance}. Returns immediately. Costs
credits at submit.
generate_video(prompt required, model?, seconds?: int 4-30, resolution?:
"480p"|"720p"|"1080p", ratio?, start_image?: an image id from
generate_image or list_history ("image/<id>" or the bare id, same project
as the video), project_id?) -> {job_id: "video/<id>", credits, model,
seconds}. Returns immediately. Costs credits at submit. start_image makes
it image-to-video: the render starts from that exact frame. Whether a
model wants one is not a guess — every video row in list_models carries
`imageInput`:
"start-required" must have start_image; the prompt says what happens next
"image-required" needs at least one image; start_image satisfies it
"optional" renders from words alone; start_image steers it if given
"none" text-only; a start_image is refused before any charge
One caveat, scoped exactly: Seedance 2.0's safety checker sometimes
refuses photorealistic PEOPLE in reference images (only people — props,
places and stylized art are fine), and the app auto-retries that refusal
with the cast described in words, at no extra charge.
generate_voice(text required, voice: id required — an invalid one is named
back by the server, project_id?) -> {job_id: "voice/<project_id>/<id>",
project_id, credits}. Returns immediately. Costs credits at submit.
wait_for_job(job_id required, timeout_s?: max 60 on stdio / 55 on hosted,
default 55) -> polls; {done:true, url} once ready, {done:false,
status:"rendering"} if not — call again with the same job_id when done is
false. A real render failure comes back isError:true with the server's own
message.
download_file(job_id required, path?: must resolve inside the current
working directory, default is a slugged filename there) -> stdio only.
Waits briefly, then saves the file and returns {saved: <absolute path>}.
list_models() -> the model catalogue, priced in credits. Image rows carry
`credits`; video rows carry `perSecond` per resolution, `creditsFrom`,
and `imageInput` (see generate_video) — pick video models by that field,
never by name.
get_credits() -> the account's credit balance.
list_history(kind?: "video"|"image"|"voice", limit?: 1-200 default 20,
project_id?: required to see voice, no account-wide voice listing) ->
{items: [{job_id, status, text}]}, newest first.
list_recipes() -> {recipes: [{slug, kind: "video"|"image", label, blurb,
prompt, model, seconds?, ratio, resolution?, credits}]}. Tap-to-use ad
recipes, bake-off-proven complete orders. kind routes the submit: video rows
go through generate_video; image rows (the Brand pack) go through
generate_image. Submit verbatim; tweak only the words, never the settings.
CLI: none yet — call the tool.
## The brand workflow
Campaign consistency comes from ONE image, not from prompt discipline.
Run the "brand-kit" recipe once (or "brand-kit-from-logo" when the user has a
real logo uploaded as a project image) — the result is a brand kit: logo,
palette, typography and tagline in a single picture. Then pass that image's
id in `reference_images` on every static you make after it — the
campaign-poster, street-billboard, product-on-white and social-banner recipes
are written expecting it — and as `start_image` (or a reference) on videos.
The kit is an ordinary image in the project; find it again with
list_history(kind: "image").
list_projects() -> {projects: [{project_id, name, brief?, scenes, assets,
updated}]}, newest activity first. When the user names a project ("put it
in my trailer project"), find it here and pass its project_id — a
generate_* call without one defaults to the newest (top) row. CLI:
`flummox projects`.
create_project(name: string required, max 80, brief?: string max 600 —
standing context for everything generated inside the project) ->
{project_id, name}. Free, no credits — a project is the container
generations land in. generate_* calls default to the newest project, so a
fresh one becomes the default; pass its project_id to be explicit. CLI:
`flummox project <name> [--brief <text>]` prints "<id> <name>".
## job_id formats
image/<id>
video/<sceneId>
voice/<projectId>/<id> (voice has no per-id status endpoint, so the
project id rides along)
## The submit/poll split
generate_image, generate_video, and generate_voice all return a job_id the
moment credits are spent — they never block on a render. Call wait_for_job
(or, from the CLI's stdio MCP, download_file) with that job_id afterward,
repeating the call while done is false.
## Credits
Every generate_* call spends credits at submit, not at completion. A call
that cannot be afforded fails with HTTP 402 and a JSON body:
{"error": "...", "code": "insufficient_credits", "needed": <n>, "available": <n>}.
Check price before spending: `flummox models` (CLI) or the list_models
tool. The number returned there is exactly what gets charged, not a list
price — an image model with a text-only fallback bills the fallback's
rate, because generate_image takes no reference input. (Video is
different: generate_video DOES take a start_image — see its entry.)
## Motion design skill
https://www.flummox.ai/flummox-motion-skill.md is a drop-in Claude skill
that runs a full motion-design production on these tools: plan shots →
generate style frames → SHOW them and get approval → quote the exact price
→ render with start_image chaining. Fetch it when the user wants a
motion-design piece, an animated ad, or a multi-shot branded video.
## Humans
https://www.flummox.ai/developers — the same information with a UI, priced
model tables, and the claude.ai connector button.
No agent in the loop? The two doors inside it, for humans: on claude.ai, add https://www.flummox.ai/api/mcp under Settings → Customize → Connectors; in a terminal, npm i -g flummox-cli && flummox login. The same document lives at https://www.flummox.ai/llms.txt. For motion design there is a drop-in skill — download flummox-motion-skill.md and add it to Claude: it plans shots, shows you style frames for approval, quotes the exact price, and only then renders.
Commands
Everything the app does, from a shell.
Read commands print to stdout; generate commands write the file and print where it landed. Every flag here is real — see --help on any command for the rest.
| Command | What it does |
|---|---|
flummox login [--name <name>] | Connect this machine to your Flummox account — browser approval, no API keys. |
flummox logout | Forget the local token on this machine. |
flummox whoami | Connection and credit check. |
flummox models | The model catalogue, priced — the same table below. |
flummox credits | Your workspace’s credit balance. |
flummox projects | Your projects, newest activity first. |
flummox project <name> [--brief <text>] | Create a project — free, the container generations land in. |
flummox image <prompt> [-m <model>] [--ratio <ratio>] [--project <id>] [-o <path>] | Generate an image. |
flummox video <prompt> [-m <model>] [--seconds <n>] [--resolution <res>] [--ratio <ratio>] [--start <image/<id>>] [--project <id>] [-o <path>] | Generate a video. --start makes it image-to-video from one of your stills. |
flummox voice <text> --voice <id> [--project <id>] [-o <path>] | Generate a voiceover. |
flummox history [--kind <kind>] [--limit <n>] [--project <id>] | Recent generations across image, video and voice. |
flummox download <kind/id> [-o <path>] [--project <id>] | Download a finished render, e.g. video/<id>. |
flummox mcp | Run the MCP server over stdio, for agents. |
Models
The real catalogue, priced.
19 models — 7 for image, 12 for video — read live from the same table the app charges against and flummox models prints. Credits, not dollars: the same unit the app spends everywhere else.
Image
| Model | Credits / image |
|---|---|
| GPT Image 2 | 48 |
| Nano Banana Pro | 45 |
| Flux Kontext runs as Flux Ultra — these tools take no reference image | 18 |
| Flux Ultra | 18 |
| Seedream 4.5 | 13 |
| Nano Banana 2 | 37 |
| Flux 2 Pro | 15 |
A model with a text fallback (marked above) has no text-to-image endpoint of its own and bills the fallback’s rate here, always — flummox image and generate_image have no reference-image input, so the lower price on the in-app picker, which does accept one, never applies through these tools.
Video
| Model | Credits / second, by resolution | From |
|---|---|---|
| Seedance Lite | 720p · 14 480p · 14 | from 42 |
| Seedance 1.5 Pro | 720p · 16 1080p · 36 480p · 8 | from 29 |
| Seedance 2.0 | 720p · 92 1080p · 207 480p · 41 | from 164 |
| Seedance 2.0 Fast | 720p · 74 480p · 33 | from 132 |
| Seedance 2.5 | 720p · 142 480p · 67 | from 268 |
| Wan 2.7 | 1080p · 31 720p · 31 | from 62 |
| Kling O1 | 720p · 22 | from 66 |
| Veo 3.1 | 1080p · 130 720p · 130 | from 1040 |
| Veo 3.1 Fast | 1080p · 46 720p · 46 | from 368 |
| Kling 3.0 | default · 39 | from 117 |
| LTX 2.3 | 1080p · 25 1440p · 49 2160p (4K) · 97 | from 150 |
| Wan 2.7 from a frame | 1080p · 46 720p · 31 | from 62 |
Connections live in Settings → Connected agents; disconnect ends them instantly.