Build with the API

Base URL and auth

API requests use a bearer token. Create API keys from the Brainy Canvas account menu.

BASE_URL="https://brainycanvas.com"
Authorization: Bearer bc_live_...

Endpoints

Generate image or video

Media generation is asynchronous. Discover configured models first, then create a job and poll its Location URL until the status is succeeded or failed. Use an idempotency key for every retryable create call. The same key and request return the original job; changing the request returns IDEMPOTENCY_CONFLICT. Video output controls are model-specific, so use the resolution, audio, and bitrate capabilities returned by model discovery. Unsupported controls are rejected before credits are reserved.

curl "$BASE_URL/api/cli/media/models?kind=image&operation=generate" \
  -H "Authorization: Bearer $BRAINY_CANVAS_API_KEY"

curl "$BASE_URL/api/cli/media/generations" \
  -H "Authorization: Bearer $BRAINY_CANVAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-2026-08-18-hero-v1" \
  -d '{
    "kind": "image",
    "operation": "generate",
    "preset": "campaign-image",
    "model": "auto",
    "prompt": "A clean studio campaign image for a cobalt travel bottle",
    "aspectRatio": "4:5",
    "inputs": [],
    "parameters": {},
    "metadata": { "campaignId": "fall-launch" }
  }'

curl "$BASE_URL/api/cli/media/generations/GENERATION_ID" \
  -H "Authorization: Bearer $BRAINY_CANVAS_API_KEY"

Supported stable presets are campaign-image, localized-image, stock-image, product-swap, product-video, ugc-video, and multi-shot-video. Use model: "auto" unless you need a specific configured model. The stable aspect ratios are 1:1, 4:5, 9:16, and 16:9.

Reference inputs

Upload private files with /api/cli/uploads, then pass the returned URL with its MIME type and semantic role. Public HTTPS URLs are downloaded through private-network, redirect, MIME, byte-size, and image dimension checks, then copied into your Brainy Canvas storage before the provider is called.

{
  "kind": "image",
  "operation": "edit",
  "preset": "product-swap",
  "model": "auto",
  "prompt": "Place the product naturally on the marble counter",
  "aspectRatio": "4:5",
  "inputs": [
    { "url": "UPLOAD_URL_1", "mimeType": "image/png", "role": "scene" },
    { "url": "UPLOAD_URL_2", "mimeType": "image/png", "role": "product" }
  ],
  "parameters": { "preserveLayout": true },
  "metadata": {}
}

Create a project

curl "$BASE_URL/api/cli/projects" \
  -H "Authorization: Bearer $BRAINY_CANVAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Product storyboard"}'

Add a node

curl "$BASE_URL/api/cli/projects/PROJECT_ID/nodes" \
  -H "Authorization: Bearer $BRAINY_CANVAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "position": { "x": 0, "y": 0 },
    "data": { "text": "Draft a launch storyboard for our new feature." }
  }'

Connect nodes

curl "$BASE_URL/api/cli/projects/PROJECT_ID" \
  -H "Authorization: Bearer $BRAINY_CANVAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"TEXT_NODE_ID","target":"CHAT_NODE_ID"}'

Run work

curl "$BASE_URL/api/cli/projects/PROJECT_ID/nodes/NODE_ID/run" \
  -H "Authorization: Bearer $BRAINY_CANVAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"gpt-4o-mini","instructions":"Keep the answer concise."}'

Upload a file

curl "$BASE_URL/api/cli/uploads" \
  -H "Authorization: Bearer $BRAINY_CANVAS_API_KEY" \
  -F "file=@./brief.pdf"

Error codes

Common errors include UNAUTHORIZED, INSUFFICIENT_CREDITS, RATE_LIMITED, TIER_LOCKED, MODEL_NOT_FOUND, and INVALID_REQUEST. Media calls may also return MODEL_UNAVAILABLE, UNSUPPORTED_OPERATION, INPUT_FETCH_FAILED, INPUT_TOO_LARGE, IDEMPOTENCY_CONFLICT, and QUEUE_UNAVAILABLE.