# Bannerbear setup for PopMCP

You paste one value into PopMCP: a Bannerbear API key starting with bb_ak_v5_, created on the API Keys page of your Bannerbear dashboard. A Project API key from an older V2 project works too.

- Auth: API credentials
- Setup time: 2 min
- API base URL: https://api.bannerbear.com/v5
- Credentials screen: https://app.bannerbear.com/v5/api_keys
- Provider docs: https://developers.bannerbear.com/

## Before you begin

- A Bannerbear account. The free trial includes 30 API credits and needs no card
- At least one template in Bannerbear to render from, or one installed from the template library
- Enough credits for what you plan to run: every image, animation and video spends API credits, and AI tools spend AI credits

## Get your credentials

### 1. Sign up or sign in at bannerbear.com

Create a Bannerbear account or sign in. A new account starts on a free trial with 30 API credits and no card; you can pick a plan later. If your dashboard offers a version switcher, stay on the current version (V5) for a new key.

Screen: https://app.bannerbear.com/

### 2. Open API Keys and create a key

Open API Keys (app.bannerbear.com/v5/api_keys) and create a new key. Give it a name such as PopMCP. Leave Scopes empty for full access, or tick only what your AI should do, such as `image_templates:read` and `images:write`. Leave Allowed origins empty, because PopMCP calls Bannerbear from its servers, not from a browser.

Screen: https://app.bannerbear.com/v5/api_keys

### 3. Copy the key

Copy the new key. It starts with `bb_ak_v5_`. You can roll it later to get a new value, or delete it to cut PopMCP off.

Screen: https://app.bannerbear.com/v5/api_keys

### 4. Using an older V2 project instead

If your templates live in a V2 project, open that project, then Settings, API Key, and copy the Project API Key. A V2 key and a V5 key are not interchangeable: each reaches only its own API, and PopMCP shows the tools that match the key you paste. A V2 Master API key also works if you paste the project's uid under More options, Project ID.

Screen: https://app.bannerbear.com/

### 5. Paste the key into PopMCP

In PopMCP, paste the key into API key and connect. PopMCP checks it by reading your workspace (or V2 project), plan and credits from Bannerbear, and loads the tools for that key's version.

## Fields PopMCP asks for

- API key (apiKey) [required]: In Bannerbear open API Keys, create a key and copy it (it starts with bb_ak_v5_). For an older V2 project, copy the Project API key from the project's Settings, API Key. Stored encrypted and used only on our servers.
- Project ID (V2 Master API key only) (projectId): Only for a V2 Master API key, which reaches every project: the uid of the project to connect. Leave it empty for any other key.

## Verify

PopMCP marks the Bannerbear connection Verified with your workspace name (or the V2 project's name) and records the plan, the credits left and the key's scopes. Asking the AI to list your templates returns them with their uids and sizes.

## Troubleshooting

### "Bannerbear did not accept this API key..."

Cause: The key was copied incompletely, deleted or rolled, or a signing key was pasted instead of an API key.

Fix: Create or roll a key under **API Keys** and paste the whole key, which starts with bb_ak_v5_. For a V2 project, copy the Project API key again from the project's **Settings**, **API Key**.

### "This is a Bannerbear Master API key, which reaches every project..."

Cause: A V2 Master API key was pasted without a project.

Fix: Open **More options** and paste the uid of one of the projects listed in the message, or paste that project's own Project API key instead.

### Tools fail with 403

Cause: The key's scopes do not cover what the AI tried, or the template only lets its owner's keys change it.

Fix: The error names the missing scope, for example images:write. Add it to the key under **API Keys**, or ask the template's owner to allow team changes.

### Tools fail with 402

Cause: The workspace has used up this month's API credits, or its AI credits for AI tools.

Fix: Top up or upgrade in Bannerbear, or wait for the monthly reset. The AI can check the balance with get_account.

### The AI says a tool is for the other API version

Cause: V5 and V2 keys are not interchangeable, and the AI picked a tool for the other version.

Fix: Nothing to change: the message names the tool that does the job with your key, and the AI uses that one.

---

Source: https://www.docs.popmcp.com/docs/integrations/bannerbear/