API reference

Every request carries the key in an Authorization header:

Authorization: Bearer msk_live_...

Keys are created and revoked from Settings → API keys by a team owner or admin. A key acts on behalf of its whole team, not a single member — generations, assets and workflow runs it creates are visible to the whole team, and its spend counts against the team's shared credit balance.

Each key carries one or both of two scopes, set at creation time:

• read — list/view assets and generations. Cannot spend credits.
• generate — start generations, upload assets, run workflows. Spends the team's credits.

A request to an endpoint the key's scopes don't cover returns 403 insufficient_scope.

Verify a key and see the team's current plan, scopes and credit balance:

curl https://api.makeshape.studio/api/v1/me \
  -H "Authorization: Bearer msk_live_..."

# {
#   "team_id": "...",
#   "plan": "pro",
#   "scopes": ["read", "generate"],
#   "credits": { "balance": 1850 },
#   "monthly_cap": { "allowed": true, "available": 240 }
# }

Generations are asynchronous — enqueue one, then poll it until it completes:

curl -X POST https://api.makeshape.studio/api/v1/generations \
  -H "Authorization: Bearer msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": "image",
    "model_id": "fal-ai/flux-2/flash",
    "prompt": "a red sneaker on a white background, studio lighting"
  }'
# { "generation_id": "...", "status": "queued" }

curl https://api.makeshape.studio/api/v1/generations/<generation_id> \
  -H "Authorization: Bearer msk_live_..."
# { "status": "completed", "output_url": "https://...", ... }

Use GET /api/v1/capabilities to discover valid category_id/model_id combinations and their credit cost before submitting a request.

const API = "https://api.makeshape.studio";
const KEY = process.env.MAKESHAPE_API_KEY;

async function removeBackground(imageAssetId) {
  const res = await fetch(`${API}/api/v1/generations`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ category_id: "background", image_asset_id: imageAssetId }),
  });
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
  const { generation_id } = await res.json();

  // Poll until the generation leaves "queued"/"processing".
  while (true) {
    const gen = await fetch(`${API}/api/v1/generations/${generation_id}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    }).then((r) => r.json());
    if (gen.status === "completed") return gen.output_url;
    if (gen.status === "failed") throw new Error(gen.error);
    await new Promise((r) => setTimeout(r, 2000));
  }
}

The same API key also works as an MCP (Model Context Protocol) connector, so agents like Claude or Cursor can act on your team's assets and generations directly — no custom integration code needed. It's a thin layer over the same /api/v1 endpoints above, exposed as a curated set of task-shaped tools rather than the raw category/model taxonomy:

Add it to any MCP-compatible client with the server URL and your key as a bearer token:

{
  "mcpServers": {
    "makeshape-studio": {
      "url": "https://mcp.makeshape.studio/mcp",
      "headers": {
        "Authorization": "Bearer msk_live_..."
      }
    }
  }
}

Tools that spend credits (all but list_assets and get_generation) run against the same monthly cap and team credit balance as everything else on this page — an agent looping on a key can't spend past its cap.

• 300 requests per 15 minutes, per key (not per IP) — standard RateLimit-* response headers report your remaining quota.
• An optional monthly credit cap can be set per key at creation time — independent from, and in addition to, the team's overall credit balance. Exceeding it returns 402 api_key_cap_exceeded without touching the team's other keys.
• Credits are metered after the fact against the model provider's real cost, not an upfront estimate — a request already in flight when a cap or balance is exhausted is still allowed to complete.

Every error is a JSON body with an error code: