AgentBoard
Base URL: https://agentboard.fly.dev. All examples below use REST. MCP tools accept the same argument shapes — same field names, same JSON structure. No client credentials are required to call the hosted endpoints.
Data model
- Project — UUID,
aspectRatio (default 1.7777), ordered list of boards.
- Board — 5-char
uid, dialogue, action, notes, duration (ms), up to 6 layers (fill is primary; others: tone, pencil, ink, reference, notes).
- Layer asset — one image per
(board, layer). Re-upload replaces.
- Audio asset — one audio per
(board, kind). Kinds: narration, sfx, music, ambient, reference. Multiple kinds per board allowed.
Workflow
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:
| Field | What | Use for |
|---|
imagePath / audioPath | Local file path | Preferred when the user has explicitly produced or pointed at a file. MCP subprocess reads and uploads the bytes. Never reference paths the user didn't authorize. |
imageUrl / audioUrl | http/https URL | Remote CDN links (the MCP subprocess fetches them). Zero agent context cost. |
imageBase64 / audioBase64 | Inline base64 | Only for tiny images (<10 KB). Burns agent context at 1.33× file size. |
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:
| Type | Required fields |
|---|
line | from, to |
circle | center, radius |
rect | topLeft, size: [w,h] |
arrow | from, to |
text | position, text |
polyline | points: [[x,y], ...] |
polygon | points: [[x,y], ...] |
bezier | from, cp1, cp2, to |
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.
| Endpoint | Purpose | Key fields |
|---|
POST /api/agent/generate-image | AI image | prompt, style?, quality?, model? |
POST /api/agent/generate-speech | Text-to-speech | text, voice? |
POST /api/agent/generate-sfx | Sound effect | prompt, durationSeconds? (0.5–22) |
POST /api/agent/generate-music | Music | prompt, musicLengthMs? (3000–600000) |
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:
| Code(s) | HTTP | Action |
|---|
BAD_REQUEST, BAD_BASE64, BAD_MIME, BAD_DRAW | 400 | Fix request shape |
UPLOAD_TOO_LARGE | 413 | Resize/compress (images > 256 MB, audio > 512 MB) |
WRONG_PROJECT, FORBIDDEN | 403 | Check projectId match |
NO_BOARD, NOT_FOUND | 404 | Refetch via GET /api/agent/project/:id |
VERSION_MISMATCH | 409 | Refetch, merge, retry |
PROVIDER_REJECTED | 422 | Fallback generator rejected (moderation or voice-locked) |
RATE_LIMITED | 429 | Exponential backoff |
| (none) | 402 | x402 payment required — retry with X-Payment header |
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.
