Docs

Wildfield is an AI-native ad creative builder. The north star is simple: an agent receives a brief, connects over MCP, and sets the whole campaign up - design system, scenes, imagery, motion, background video, sound, and a render. This page is the contract that makes that possible: every tool, schema, and motion rule the editor actually ships.

Quickstart

From a brief to a ready campaign. Call the tools in this order; skip a step only when the project already has that piece.

MCP Server Setup

Add the Wildfield MCP server to your agent's configuration. You'll need an API key from the Admin panel.

Hosted server (recommended, zero-install)

Nothing to clone, no npm, no npx. Point your agent at the hosted endpoint and pass your API key as a header. This is the easiest way to connect: the server runs on wildfield.io.

claude mcp add --transport http wildfield https://wildfield.io/api/mcp \
  --header "X-API-Key: adk_your_api_key_here"

Or as JSON (Claude Desktop / any MCP client that speaks the Streamable HTTP transport):

{
  "mcpServers": {
    "wildfield": {
      "type": "http",
      "url": "https://wildfield.io/api/mcp",
      "headers": {
        "X-API-Key": "adk_your_api_key_here"
      }
    }
  }
}

Your key authenticates every request and attributes usage/credits to your account. A missing or invalid key returns 401. The hosted server exposes the exact same tools as the local methods below.

The endpoint is stateless Streamable HTTP, so it accepts POST only: GET and DELETE return 405 (there is no SSE stream to open and no session to terminate). It authenticates with the X-API-Key header only. An Authorization: Bearer token is never read here, even though it appears in the CORS allow-list, so a client that sends one instead of the key gets 401. There is also a per-key burst limit of 120 requests per 60 seconds (fail-open), and the function itself is capped at 300 seconds.

Local server (offline / dev only)

Only needed if you're running offline or hacking on the server itself. Most people should use the hosted URL above. You'll need a checkout of the Wildfield repo and Node 18+. The mcp-server/ folder on its own is not enough: its tools import shared code from the repo's lib/ folder, so keep the two side by side.

First install its dependencies (just @modelcontextprotocol/sdk and zod; the repo root's npm install is not needed):

cd mcp-server && npm install

Then point your agent at the server's absolute path and pass your key via the environment. ADFLOW_API_KEY is required; ADFLOW_URL is optional (defaults to https://wildfield.io).

{
  "mcpServers": {
    "wildfield": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"],
      "env": {
        "ADFLOW_API_KEY": "adk_your_api_key_here",
        "ADFLOW_URL": "https://wildfield.io"
      }
    }
  }
}

Replace /absolute/path/to/mcp-server/index.js with the real path on your machine (e.g. /Users/you/wildfield/mcp-server/index.js). A published npx wildfield-mcp package is coming soon. It is not on npm yet, so don't rely on it today.

Authentication reference

Every request is authenticated with your Wildfield API key. Create keys in Admin → API Keys. How you supply the key depends on the method:

MCP Endpoints

57 tools available via the MCP server. All return JSON. You call these by tool name (not by HTTP verb) - the coloured badge below each tool indicates the HTTP method of the REST endpoint it wraps, for reference when using the Direct API Fallback.

Characters

A character lives on its design system and a project picks some by id (preset.characterIds), as in the editor. Its fields: name, prompt (free notes), details (role, age, height, bodyType, personality, faceShape, eyes, eyebrows, nose, lips, skin, hair, makeup), marks ({ text, side }, side is the character's own left, right, both or centre), wardrobe ({ name, material, colour }, colour a hex), panels (profile, turnaround, face, costume, palette on; expressions, poses off) and photos ({ url, role, label }, role identity, clothing, shoes or accessory).

Reads also return portrait (the full-resolution, front-facing portrait on white: the character's thumbnail and the face its sheets are drawn from; portraitSource is portrait, or front still / close-up still for a character made before portraits), sheet (main = character sheet, detail = detail sheet, current false once the look changed) and sceneDetails, the CHARACTER DETAILS text every scene prompt gets. Typical flow: create_character with projectId, generate_character_sheet, then generate_image with characterIds.

Design System Schema

The complete field reference for design systems. All fields are required for correct rendering.

Project Schema

The full project object structure returned by get_project and expected by update_project.

{
  "version": 2,
  "designSystemId": "client-slug",
  "preset": { /* full design system snapshot */ },
  "activeFormat": "square",
  "activeSceneId": "scene-uuid",
  "totalDuration": 12,
  "scenes": [ /* array of scene objects */ ]
}

Scene Schema

A scene may contain any of these fields. Almost all are optional. Missing fields fall back to design-system and editor defaults, so a scene only needs the fields it actually sets.

Format Specifications

Font sizes are calculated by the renderer, not stored. The root unit determines all text sizes via multipliers.

Per-scene scale overrides: h1Scale, h2Scale, h3Scale, ctaScale (percentage, default 100).

Vector Expressions

Vector text layers accept inline expression tokens wrapped in curly braces. Each token evaluates live against the scene clock, so a single text string can count a number, cycle through words, type on, or print a stable random digit, with no keyframes. Tokens evaluate identically in preview and in server render, and a token persists across linked scenes (the linked clips share one timeline window, so a {0-100} ramps once across the whole chain rather than restarting at each cut).

Where to type them: Canvas mode → a Vector layer → the text field (placeholder Type text…). Any glyph/string entry in the layer's text stack accepts tokens. There is no MCP parameter: expressions live inside the text content itself.

Number animation: decimals and direction

The decimal precision of the output matches the inputs: the result is shown to max(decimals of A, decimals of B) places. Both-integer inputs stay integer (rounded). Descending ranges (B < A) animate backwards.

Examples

Raised {0-100}% this quarter      → counts 0 → 100 over the scene
Only {50-0} left!                    → counts down 50 → 0
{Save big, Move fast, Win}          → three words, ~33% each, last holds
Gate {random}, Seat {random}          → two independent stable digits
{0-100}% / {loading, almost, done}     → a counter and a word cycle in one line
{0-9999|$} off                              → $0 … $9,999
{dogs,cats,cows:s0.5}                      → words, each character fades on over 0.5s
{type:LIMITED TIME}                         → types on across the scene

Behaviour & gotchas

Verified against app.html: the token runtime vexprEvalCore (parse + interpolation) and the live updater __vectorExprRuntime.

Animate & Guide Physics

Animate Physics is a particle engine on a Vector layer. Each glyph or SVG becomes many copies. Eight forces push those copies around the frame. The same numbers drive preview and the cloud MP4, because the runtime is a pure function of time and seed. An untouched panel is a no-op (all forces 0). Flip the Engine switch on, then either dial forces or pick a Recipe.

Call get_motion_skill then apply_physics_recipe. Do not invent ranges or gsapCode.

How a field feels

Layout and globals

Layout is structural. On a linked chain, count is owned by the first scene so particle i stays the same particle across the cut. Forces and globals can ramp from Start to End on that scene; they also lerp across a LINK, the same way Scale does.

Click a number to type past the slider. The track is the useful band; extremes are opt-in.

Engine, Perfect loop, Trail, Recipes

Guide Physics and Form Sources

Guide Physics sits on top of the running field. A prompt such as "form a ring" or "rotate 360" bakes a { formation, modifier } spec. Physics still runs underneath. Clear the shape and you are back to pure forces; the modifier (Motion's Displace), Follow and Emit stay.

In the Canvas panel (v1.999.0) this is three cards over the same physics.guide fields: Shape (saved id guide-physics: the formation from a prompt, a generator, an image, an SVG or data, and its Reveal), Draw (id drawing: the path or mask in layer.draw, Smoothness, Show guide, Fill mask) and Follow / Emit (id follow-emit: guide.followPath or guide.emitter, one job at a time). No field moved, so saved projects render exactly as before.

Form Sources (on by default) feed that formation from something other than a prompt:

A to B across a LINK: each linked scene can hold its own formation. Particles melt from shape A to shape B across the cut. Count stays locked so identity holds. Ease on the Keyframes panel (Slow finish, etc.) shapes both the pose and the physics clock.

Gradient FX (animated linear / conic / mesh / aurora) is on by default. Opt out with ?gradientFx=off.

Verified against app.html v1.484.0: PHYSICS_DEFAULTS, slider arrays, FORMATION_MAX 800, FORM_SOURCES / GRADIENT_FX default on, one pose per layer at kf.t.

Editor Feature Map

The editor's user-facing creative surface, beyond the API/MCP layer above. Most features are always visible; a few are flag-gated (enable via URL param or localStorage as shown above). This map reflects the shipping product. See the dedicated sections above for expressions and physics.

Agent Skills

Skills are prompt modules your agent can invoke to get context-aware guidance for specific tasks. Install the wildfield skill in your agent to unlock all MCP tools and workflow knowledge.

Core Skill

JSON Templates

Download these templates, fill in your client's brand details, and import via the API or MCP tools.

Design System Template

{
  "id": "your-client-slug",
  "name": "Your Client Name",
  "uiAccent": "#2563eb",
  "colorVars": [
    { "hex": "#2563eb", "name": "Primary" },
    { "hex": "#1e40af", "name": "Secondary" },
    { "hex": "#0a0a0a", "name": "Dark" },
    { "hex": "#f5f5f5", "name": "Light" }
  ],
  "fontHeadline": "'Inter', sans-serif",
  "fontBody": "'Inter', sans-serif",
  "fontH1": "'Inter', sans-serif",
  "fontH2": "'Inter', sans-serif",
  "fontH3": "'Inter', sans-serif",
  "fontCta": "'Inter', sans-serif",
  "fontImport": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&display=swap",
  "h1Weight": "900",
  "h2Weight": "400",
  "h3Weight": "400",
  "ctaWeight": "700",
  "h1Transform": "none",
  "h2Transform": "none",
  "ctaTransform": "uppercase",
  "h1LetterSpacing": "-0.02em",
  "h2LetterSpacing": "0",
  "ctaLetterSpacing": "0.05em",
  "ctaRadius": "4px",
  "ctaAlign": "center",
  "contentAlign": "left",
  "contentPosition": "middle",
  "logoPosition": "top-left",
  "logoScale": 100,
  "logoSvg": "",
  "logoFileName": "",
  "disclaimer": "",
  "disclaimerAlign": "left"
}

Project Template

{
  "name": "My Campaign Name",
  "designSystem": "your-client-slug",
  "scenes": [
    {
      "h1": "Your Main Headline",
      "h2": "Supporting copy goes here",
      "h3": "",
      "cta": "Call To Action",
      "bgType": "colour",
      "bgColor": "#0a0a0a",
      "notes": "Scene description or AI image prompt",
      "duration": 6
    },
    {
      "h1": "Second Scene",
      "h2": "Another supporting message",
      "h3": "",
      "cta": "Learn More",
      "bgType": "gradient",
      "bgColor": "#1e40af",
      "notes": "",
      "duration": 6
    }
  ]
}

Preview loop vs Perfect loop vs Export loops

Direct API Fallback

When MCP tools aren't available, use the REST API directly with your API key.

# List design systems
curl -s -H "X-API-Key: YOUR_KEY" "https://wildfield.io/api/design-systems/list"

# Save / update design system
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/design-systems/save" \
  -d '{"id": "client-slug", "data": { ... }}'

# List projects
curl -s -H "X-API-Key: YOUR_KEY" "https://wildfield.io/api/projects/list"

# Get project by UUID
curl -s -H "X-API-Key: YOUR_KEY" "https://wildfield.io/api/projects/PROJECT_UUID"

# Create new project
# project blob MUST include version, designSystemId, preset.name, activeFormat
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/projects/save" \
  -d '{"filename": "project-slug", "project": {"version":2, "designSystemId":"client-slug", "preset":{"name":"Client Name"}, "activeFormat":"square", "scenes":[...]}}'

# Update existing project
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/projects/save" \
  -d '{"filename": "project-slug", "projectId": "UUID", "project": {"version":2, "designSystemId":"client-slug", "preset":{"name":"Client Name"}, "activeFormat":"square", "scenes":[...]}}'

# ─── AI generation (genai/*): all POST, all return a blob URL ───

# Generate an image from a text prompt
# model: flux-dev (default), flux-pro, imagen4, imagen4-fast, gpt-image-1, nano-banana-pro, ideogram-v3, recraft-v3, recraft-v3-transparent
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/genai/generate" \
  -d '{"model":"flux-dev", "prompt":"a red sports car at sunset", "width":2160, "height":2160, "filename":"car.png", "design_system_id":"client-slug"}'

# Edit an existing image with an instruction (the editing suite)
# Same shape applies to /api/genai/inpaint, /retouch, and /enhance
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/genai/edit" \
  -d '{"model":"nano-banana-pro", "prompt":"make the sky stormy", "image_url":"https://.../car.png", "filename":"car-edited.png"}'

# Outpaint / extend an image (fill new pixels around the frame)
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/genai/outpaint" \
  -d '{"image_data":"data:image/png;base64,...", "expand_top":0, "expand_bottom":256, "expand_left":0, "expand_right":0, "prompt":"more road", "filename":"car-extended.png"}'

# Animate an element / scene into a video clip
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/genai/animate" \
  -d '{"prompt":"slow pan across the car", "duration":6, "format":"mp4", "width":1080, "height":1080}'

# List your past generations
curl -s -H "X-API-Key: YOUR_KEY" "https://wildfield.io/api/genai/list"

# ─── Renders (renders/*) ───

# Rasterise composition HTML to a PNG screenshot (server-side Puppeteer)
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/renders/screenshot" \
  -d '{"html":"<!doctype html>...", "width":1080, "height":1080}'

# Render composition HTML to a video on AWS Lambda (returns an executionArn)
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://wildfield.io/api/renders/video" \
  -d '{"html":"<!doctype html>...", "width":1080, "height":1080, "fps":30, "quality":"high", "format":"mp4"}'

# Poll render progress (executionArn returned by /renders/video)
curl -s -H "X-API-Key: YOUR_KEY" "https://wildfield.io/api/renders/progress?executionArn=ARN"

Critical Rules