Agents
Let a coding agent generate images and video with Windpaint through the MCP server, the skills plugin, or the CLI.
Agents use Windpaint the same way you do: they read the live catalog, estimate the cost, submit a job, wait for it and download the output. Everything they make lands as an asset in your project and is billed to your organization’s credits, like any other API call.
The shortest path, in Claude Code:
export WINDPAINT_API_KEY=aak_...
claude
/plugin marketplace add windpaint-ai/skills
/plugin install windpaint@windpaint
Then ask for something: “Generate a 16:9 image of a lighthouse at dusk with Windpaint and save it to ./out”.
Three ways in
MCP server
20 tools on the hosted server at https://mcp.windpaint.ai/mcp. Works with any MCP client.
Skills plugin
Five skills that teach the agent the workflow (estimate first, wait, never resubmit), plus the MCP server, in one install.
CLI
The windpaint binary with --json. For agents that run shell commands and have no MCP support.
| Skills plugin | MCP server only | CLI | |
|---|---|---|---|
| What the agent gets | Tools and instructions for using them | Tools | Shell commands with JSON output and stable exit codes |
| Clients | Claude Code, Codex, Cursor | Any MCP client that supports streamable HTTP and custom headers | Any agent with a shell |
| Local files | Upload by URL or base64, download by signed URL | Upload by URL or base64, download by signed URL | Local paths work |
| Setup | One plugin install plus WINDPAINT_API_KEY | One config entry | Install the binary plus WINDPAINT_API_KEY |
Which to pick
- Claude Code, Codex or Cursor: install the skills plugin. It connects the MCP server for you, and the skills tell the agent to estimate video jobs before running them, to wait instead of resubmitting, and to read models and prices from the API instead of guessing.
- Another MCP client (your own agent, or any client that can send custom headers): add the MCP server directly. If your agent reads skill files, add them too with
npx skills add windpaint-ai/skills. - Agent that works on local files a lot, such as animating images already in your repo: give it the CLI as well. The MCP server can’t read your disk; the CLI uploads local paths and saves outputs directly.
- Agent writing code that calls Windpaint (not generating media itself): the
windpaint-apiskill covers that. You don’t need the MCP server for it.
Set up an API key
Every surface authenticates with a Windpaint API key (aak_ followed by 48 hex characters).
Create a key
Export it in the shell that starts your agent
export WINDPAINT_API_KEY=aak_...
Put it in your shell profile or a secrets manager. The plugin configs read it from the environment, so it never has to be pasted into a config file or into the chat.
Optional: pick a project
Jobs and assets go to your organization’s default project unless you say otherwise. To keep an agent’s work separate, create a project in Settings → Projects and send its id or slug as the X-Windpaint-Project header to the MCP server, or set WINDPAINT_PROJECT for the CLI. See Organizations and projects.
Give each agent its own key. You can see which key made which job, and revoking one key (it stops working immediately) doesn’t break your other integrations. A key acts with its creator’s role; to give an agent less, create the key with a narrower role_id, for example the member role, which can generate but can’t manage keys, members or webhooks.
Cost guardrails
Agents spend real credits. What keeps that predictable:
- Estimate first.
estimate_costandestimate_product(CLI:windpaint estimate) return the credits a job would cost and your available balance without running anything. The skills tell the agent to estimate every video job, product run and batch, and to report the number before submitting. - Holds, not surprises. When a job is submitted, its estimate is held from your balance. If the organization can’t cover it, the API refuses the job with
402 billing.insufficient_creditsand nothing runs. The agent sees how many credits were needed and how many are available. - Failures are free. Jobs that end
failed,nsfworcanceledrelease their hold in full. You pay only for completed outputs. - No double billing from retries, if the agent follows the rules. There are no idempotency keys: a resubmitted job is a second job, billed again. The skills tell the agent to keep waiting on a slow job instead of resubmitting it.
- Approve tool calls. The MCP server does not ask for confirmation before
generateorrun_product. Your client’s tool-approval prompt is the checkpoint, so leave it on for those tools if you want to approve each spend. - Watch the balance. Set a low-balance threshold in Settings → Billing; crossing it emails org admins. See Billing.
There are no per-key spending limits or caps today. The only hard ceiling is your prepaid balance.
What agents can and can’t do
Agents can:
- Read the catalog of capabilities, models, resolutions and prices.
- Estimate costs and read the organization’s credit balance.
- Upload reference images, start frames, video and audio (free, up to 50 MiB).
- Generate images and video, wait for jobs, cancel them, and download outputs.
- Run products such as text-to-clip, and follow each step.
- List and create projects, and list recent jobs, runs and assets.
Agents can’t:
- Buy credits. Top-ups happen in the dashboard; an agent that runs out tells you how many credits it needs.
- Create or revoke API keys, invite members, change roles, or manage org webhooks.
- Delete assets (there is no delete endpoint).
- Pass a third-party image URL straight into a job. Inputs must be Windpaint assets; the agent uploads the file first with
upload_asset. - Read local files through the MCP server. The agent sends file contents as base64, or uses the CLI.
- Sign in with OAuth. The hosted server takes an API key only, so clients that connect exclusively through OAuth can’t use it yet.