Blueprint Studio API v1

Authentication

All API requests require an API key sent via the Authorization header.

curl https://tools.blueprintstudio.ai/api/v1/assets \
  -H "Authorization: Bearer bp_live_your_api_key_here"

The REST API and API keys are on paid plans: Pro and Max. A Free account can also use them with Pro access from a client grant or credit pack of 600 or more credits, or with a key bound to a brand that includes Pro. Otherwise every request, read or write, answers 403 with code PLAN_REQUIRED, nextStep, plansUrl and checkoutUrl (a one-step Stripe checkout for Pro on the key's account, no sign-in); the key isn't revoked and works again once the account upgrades. AI apps connect with MCP sign-in on every plan, Free included.

Each API key is bound to one workspace: a single brand, or your personal library. A key only works in its own workspace, so a personal key can't act on brands and a brand key can't reach other brands or your personal library. Choose the workspace when you create a key in Settings, and create one key per brand you automate.

Create API keys in your account settings. Keys are hashed on our servers, so save your key when first created.

Rate Limits

The API is available on paid plans. See plans

Credits are weighted by model, size and quality, so one image is not one credit: a standard image (GPT Image 2.5 Sunburst, 2K, medium quality) costs 3 credits, and each image sent with it (a reference, logo or the image being edited) adds 1. See credits per image for every model.

• Every /api/v1 response to an API key carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds, next UTC midnight).
• Polling a generation job (GET /api/v1/generate/jobs/:id) doesn't count toward the daily limit.
• Over the limit you get 429 with code API_REQUEST_LIMIT and a Retry-After header.

Quick Start

1. Start a generation. Make up a new requestId (8 to 128 letters, digits, - and _; a UUID works), and send the same one if you retry this exact request:

curl -X POST https://tools.blueprintstudio.ai/api/v1/generate \
  -H "Authorization: Bearer bp_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a minimalist coffee cup icon", "requestId": "coffee-cup-icon-1", "async": true}'

It answers at once with HTTP 202 and a job to poll:

{
  "status": "queued",
  "jobId": "uuid",
  "pollUrl": "/api/v1/generate/jobs/uuid",
  "retryAfterSeconds": 5
}

2. Check the job until its status is completed or failed (about 20 to 60 seconds). With waitSeconds, each request waits up to that long for the result:

curl "https://tools.blueprintstudio.ai/api/v1/generate/jobs/<jobId>?waitSeconds=20" \
  -H "Authorization: Bearer bp_live_your_api_key_here"

{
  "jobId": "uuid",
  "status": "completed",
  "result": {
    "assetId": "uuid",
    "styleId": "uuid",
    "imageUrl": "https://...",
    "outputWidth": 1024,
    "outputHeight": 1024,
    "creditsCharged": 3,
    "webUrl": "https://tools.blueprintstudio.ai/asset-generator?brand=personal&asset=uuid&ref=api",
    "downloadUrl": "https://...",
    "suggestedFilename": "a-minimalist-coffee-cup-icon-1a2b3c4d.png"
  },
  "error": null
}

3. Save the image: curl -L -o <suggestedFilename> <downloadUrl>

Generation

Generate brand assets, get prompt suggestions, and brainstorm ideas using AI.

Assets

List, retrieve, delete, favorite, share, and remove backgrounds from generated assets.

Styles

Manage visual styles: list, create, update and delete custom styles, analyze images for style extraction, and manage reference images.

Brands

Manage brands: create, update, delete, manage settings, list and add official logos and brand assets, set the brand icon, and analyze websites for brand identity. An API key works only in the workspace it is bound to: a brand key can use only its own brand ID (any other returns 404), and a personal key cannot act on brands.

Uploads

Send image files that aren't at a public link: a logo to add as an official brand asset, or an image for generation. Each upload is checked by its bytes and works for 24 hours, in the key's workspace only.

API Keys

Manage API keys — list active keys, create new ones, and revoke existing keys. A key only sees and manages keys in its own workspace (its brand, or the personal library). API keys are on paid plans.

Settings

Get and update user-level settings: default style, prompt template and the preset for new images (fast, balanced or best).

Usage

Check current usage, rate limits, and remaining quotas.

Feedback

Tell the Blueprint Studio team what went wrong or what you wanted. Agents should use it when they get stuck, too.

Error Codes

MCP Tools

AI apps connect to https://tools.blueprintstudio.ai/api/mcp and sign in with OAuth, so they need no API key; see Connect your AI. Your AI app picks these tools for you. API keys are for scripts and CI: each works in one brand or your personal library only, and never belongs in a committed file.

Project Config

Create an optional .blueprint.json file in your project root as guidance for your coding agent. It does not change server defaults or grant access. Keep credentials out of this file.

{
  "outputDir": "./public/assets",
  "defaultStyleId": "your-style-id",
  "defaultAspectRatio": "1:1",
  "defaultImageSize": "2K"
}