Developer area: API keys and Explorer

Under Settings → Developer you find everything for the Bluepic API: your API keys, the Explorer to test requests, and the API reference. Every account can use it, with or without a team. How to create an image URL or an API request for a template is in Automate: create images by URL and API.

At the top, you switch between the Keys and Explorer tabs. Reference at the top right opens the documentation.

Keys

To create a new key:

1. Click New API key. A popup opens.
2. Type a name under Label, for example the name of your integration.
3. Click Create. The new key appears in the list.

Use a separate key for each integration. Then you can switch one off without breaking the others. The list shows for each key:

• Key: its name, when it was created and when it was last used.
• Secret: the key itself. The icon with the two pages in its row copies it at any time.
• Webhook signing secret: shown under every active key. You only need it to check that a webhook message really came from Bluepic.
• Status: active or revoked.
• ×: revokes the key after you confirm. From then on, every system that uses it gets a 401 error. The key stays in the list as revoked. You can't turn it back on.

Send the key as Authorization: Bearer bp_live_… to https://api.bluepic.io/v1. Keep keys on your server or in environment variables, never in public browser code or in a code repository.

Keys in a team

• A key acts for wherever the person who created it currently is: their team, or their personal account if they have no team. If you leave the team, your keys act for your personal account from then on, no longer for the team.
• Renders are billed to the owner of the template: the team if the team owns the template, otherwise the personal account.
• In a team, the renders of all keys count toward the team's rate limit.
• Team management requests, such as inviting or removing members, only work if you are an owner or admin. Your role is checked on every request. If you lose these rights, the key loses them too.
• The Keys list only shows the keys you created yourself.

Explorer

In the Explorer tab you build requests to the API and send them. When it opens, the render endpoint is selected.

• On the left, the list of endpoints: pick a different endpoint here. Search endpoints filters the list.
• Path, Query, Body: the fields of the request. Required fields have a *. The info icon next to a field explains it.
• templateId: when you pick one of your templates, the Explorer shows its canvases under canvas and its input fields under data, filled with the default values. Default canvas renders the default canvas.
• At the top right, the choice of how the request is sent: with one of your active keys, or with Studio session, which uses your Studio login. Revoked keys are not offered. A tag next to it shows how many renders you have left this minute, for example 87/100 renders this minute.
• Send: sends a real request. A render uses credits and counts toward the rate limit, whether you use a key or Studio session.
• Debug (free): shows the render request as JSON, the way the API would process it. Nothing is rendered and nothing is billed. The request does count toward the rate limit, though.
• On the right, the response with its status, duration and size: an image as a preview, a video as a player with its progress messages, other files with a Download button, JSON as formatted text. An error shows its code and message. If you used input names the template doesn't know, you see the correct ones.
• cURL, fetch (JS), Python: the same request as code, below the request. Your key is never in it. The code reads it from the BLUEPIC_API_KEY environment variable.

From Automate in the template editor, Open in Explorer opens the Explorer in a new browser tab, with the template already selected.

Rate limit

Render requests to POST /v1/renders are limited per minute:

• 100 per minute for a team,
• 10 per minute for an account without a team.

The limit applies to the whole team, not to each key. An extra key doesn't raise it. When you reach the limit, the API answers with 429 and tells you when to try again. Every render response has the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Your integration can use them to slow down before it hits the limit.

Reference

Reference at the top right opens the full API documentation in a new tab at https://api.bluepic.io/v1/docs. It lists every endpoint with its parameters and responses. You don't need to log in. The Explorer uses the same API description, so new endpoints show up there too.