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.

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 the mcp-server/ folder (from the repo or a shared tarball) and Node 18+.

First install its dependencies:

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

36 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.

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 guide and you are back to pure forces.

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
    }
  ]
}

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