AgentBoard

1. create project + boards (one call)
2. populate: upload OR generate images/audio
3. (optional) annotate via draw_shapes
4. (optional) export PDF and/or get share URL

1. Create project

POST /api/agent/create-project
{
  "title": "The Lighthouse Keeper",
  "aspectRatio": 1.7777,
  "boards": [
    { "dialogue": "...", "action": "...", "duration": 4000 },
    { "dialogue": "...", "action": "...", "duration": 3500 }
  ]
}
→ { id, project: { boards: [{ uid, number, ... }] }, viewUrl }

Save id and every board's uid from the response. Rate-limited: 50 creates/hour per IP+token.

2. Populate boards — upload your own bytes (PREFERRED)

Use this path if your runtime has image/audio generation (fal, Sora, Veo, Midjourney, Gemini, etc.). Generate with your tool, then upload. Skip to the Fallback generation section only if you can't generate.

Batch upload (3+ panels)

POST /api/agent/upload-batch
{
  "projectId": "...",
  "uploads": [
    { "boardUid": "ABC", "kind": "image", "imageBase64": "..." },
    { "boardUid": "DEF", "kind": "image", "imageBase64": "..." },
    { "boardUid": "ABC", "kind": "audio", "audioKind": "narration", "audioBase64": "..." }
  ]
}
→ 201 (all ok) or 207 Multi-Status { succeeded: [...], failed: [{ index, error }] }

Up to 100 items per call, mixing images and audio freely. Partial failures don't abort the batch.

MCP upload_assets_batch supports three input modes per item. Always prefer path/url over base64 — they cost zero agent context:

Single upload

POST /api/agent/draw
{ "projectId":"...", "boardUid":"...", "layer":"fill", "imageBase64":"...", "mime":"image/png" }

POST /api/agent/upload-audio
{ "projectId":"...", "boardUid":"...", "kind":"narration", "audioBase64":"...", "mime":"audio/mpeg" }

Caps: images ≤ 256 MB, audio ≤ 512 MB. Mime is sniffed from magic bytes (client-declared mime is ignored). Accepted: image/png, image/jpeg, image/gif, image/webp, audio/mpeg, audio/wav, audio/ogg.

3. Draw annotations

Composite shapes or brush strokes onto any board layer. Unique to AgentBoard — your image generator can't do this. Use it to annotate AI panels (circle a character, add an arrow, label a shot).

POST /api/agent/draw-shapes
{
  "projectId": "...",
  "boardUid": "...",
  "layer": "fill",
  "mode": "overlay",
  "shapes": [
    { "type":"circle", "center":[0.5,0.5], "radius":0.08, "stroke":"#cc0000", "strokeWidth":6 },
    { "type":"arrow",  "from":[0.7,0.3], "to":[0.5,0.5], "stroke":"#cc0000", "strokeWidth":6 },
    { "type":"text",   "position":[0.05,0.05], "text":"HERO", "fontSize":0.04, "fill":"#cc0000" }
  ]
}

Coordinates are normalized [0, 1] — (0,0) top-left, (1,1) bottom-right. radius, size, fontSize are also normalized (0.05 = 5% of canvas).

Modes: "overlay" (composite on existing layer — for annotating) or "replace" (blank canvas — for sketching).

Shape types:

All shapes accept stroke, fill, strokeWidth, opacity. Colors are any CSS color string.

Freeform strokes — POST /api/agent/draw-strokes with { brush, color, size, points: [[x,y]...] } per stroke. Brushes: pencil | pen | ink | marker | eraser. Eraser removes pixels — pair with mode:"overlay". Sparse point arrays get Catmull-Rom smoothed; no need to pass dense polylines.

4. Share + export

GET  /api/agent/share/{projectId}             → { viewUrl }  — public read-only HTML viewer
POST /api/agent/export/pdf { projectId }       → PDF bytes    — one page per board
POST /api/agent/share/{projectId}              → scoped share token
     body: { permission: "view|comment|edit", ttlMs: 86400000 }

Editing an existing project

POST /api/agent/set-metadata
{ "projectId":"...", "updates":[
  { "boardUid":"ABC", "dialogue":"new line", "expectedVersion":4 }
]}

Optimistic concurrency via expectedVersion. On 409 VERSION_MISMATCH: GET /api/agent/project/{id}, merge, retry. Asset uploads are last-write-wins and don't need expectedVersion.

Append boards later with POST /api/agent/add-scene (batch, body: { projectId, boards: [...] }) or POST /api/agent/add-board (single).

Optional server-side generation (skip if you can generate)

Only for agents without built-in image/audio generation. Uploading your own bytes via the primary workflow is faster and more reliable; these endpoints exist as a fallback. Any required provider configuration is handled server-side — the agent supplies only the request payload below.

Style presets (pass style): storyboard-sketch, cinematic-color, comic-panel. Enumerate via GET /api/agent/image-styles.

Quality tiers (pass quality): low (draft) | medium (balanced default) | high (final render). Project-level default settable on create-project.

Voice lookup — call GET /api/agent/voices before generate-speech to see which voices the server is configured to use.

Errors

Shape: { "error": { "code": "...", "message": "..." } }. Retry rules:

Do not invoke for

• Single one-off image generation unrelated to a narrative sequence — call your image generator directly.
• Video editing — AgentBoard produces storyboards, not finished video.
• Live interactive canvas apps — the drawing engine is command-based, not a stroke-by-stroke protocol.