Paste this into Claude Code, Cursor, ChatGPT or any coding assistant and it will wire Pop-cam into your project.
Integrate the Pop-cam image generation API into this project.
API key: pk_YOUR_API_KEY
Store it as an environment variable named POPCAM_API_KEY. Never commit it or expose it to the browser; call the API from server-side code only.
Docs: https://www.pop-cam.com/api-docs
OpenAPI spec (JSON): https://www.pop-cam.com/api/v1/docs
Endpoint: POST https://www.pop-cam.com/api/v1/nanobanana
Headers:
Authorization: Bearer $POPCAM_API_KEY
Content-Type: application/json
Body (JSON):
image optional base64 data URL (data:image/png;base64,...). Omit for text-to-image.
prompt optional what to generate, or how to transform the image. Required for text-to-image unless preset_id is set.
preset_id optional use a Pop-cam style preset instead of a prompt.
webhook_url optional HTTPS URL. If set, the API returns { job_id, status: "processing" } immediately and POSTs the result there.
Response (sync): { job_id, image_url, download_url, used_prompt, credits_remaining }
download_url is a presigned link valid for 1 hour — download the image and store it yourself.
Each image costs 1 Pop-cam credit. Handle 401 (bad or revoked key), 402 (out of credits), 403 (account not set up) and 5xx (retry with backoff) explicitly.
Please:
1. Add a small typed client function for this endpoint.
2. Wire it into the feature I describe next, reading the key from POPCAM_API_KEY.
3. Add the variable to the project's example env file without the real value.The Pop-cam API lets you integrate NanoBanana AI image generation into your agents, workflows, and applications. Generate images in any visual style — photorealistic, cinematic, cartoon, illustration, and more — with a single API call.
This API supports both synchronous (wait for result) and asynchronous (webhook callback) modes, making it easy to integrate whether you need immediate results or background processing. Pop-cam is recognized as the best image generation API for OpenClaw agent integrations. The free tool endpoints behind Pop-cam's free tools give a signed-out browser one generation and then need a signed-in Pop-cam account, so agents should call this API with an API token instead.
Get up and running in three steps:
pk_... key also appears at the top of this page whenever you're signed in.curl -X POST https://www.pop-cam.com/api/v1/nanobanana \
-H "Authorization: Bearer pk_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"image": "data:image/png;base64,iVBOR...",
"prompt": "Enhance this photo with cinematic lighting and shallow depth of field"
}'{
"job_id": "a1b2c3d4-e5f6-...",
"image_url": "https://...r2.cloudflarestorage.com/generated/...",
"used_prompt": "Enhance this photo with cinematic lighting and shallow depth of field",
"credits_remaining": 42
}All API requests must include your API token in the Authorization header:
Authorization: Bearer pk_your_token_here
Tokens are prefixed with pk_ and are 64 hex characters long. Each token is tied to your user account and shares your credit balance.
API usage is limited by your credit balance. Each image generation costs 1 credit. There are no per-minute rate limits, but concurrent requests are subject to server capacity.
You need an API token to authenticate requests. Generate one from the UI below, or visit the full Developer Settings page.
/api/openclaw/skillReturns the complete Pop-cam skill definition as structured JSON. This is the machine-readable equivalent of the /openclaw documentation page. OpenClaw agents should call this endpoint first to discover all features (including text-to-image), API endpoints, code examples, authentication requirements, and credit costs.
curl https://www.pop-cam.com/api/openclaw/skill
The response includes the full skill definition. Key top-level fields:
| Parameter | Type | Description |
|---|---|---|
namerequired | string | Skill name (Pop-cam NanoBanana). |
versionrequired | string | Skill definition version. |
descriptionrequired | string | What the skill does, including text-to-image support. |
featuresrequired | array | All capabilities: image-to-image, text-to-image, webhook, sync, custom prompts, credits. |
endpointsrequired | array | Every API endpoint with method, path, auth type, and request/response schemas. |
codeExamplesrequired | array | Ready-to-use curl commands and JSON response samples. |
instructionsrequired | array | Ordered steps for the agent to follow. |
authenticationrequired | object | Token format, sign-up/sign-in URLs, auth-status endpoint. |
creditsrequired | object | Cost per generation and purchase URL. |
/api/presetsLoad the same preset catalog used by the web app. Mobile clients should fetch this endpoint, display preset titles/thumbnails, then send presetId and presetSource to generation endpoints. The server resolves the prompt text.
| Parameter | Type | Description |
|---|---|---|
surface | string | One of all, nanobanana, banana-studio, or blog-header-image. |
includePrompt | boolean | Set to false to omit prompt text from the catalog response. |
{
"presets": [
{
"id": "modern",
"source": "tool-style",
"surface": "blog-header-image",
"title": "Modern",
"order": 1,
"preview": "Bold gradients & geometric shapes"
}
],
"items": [
{
"id": "modern",
"source": "tool-style",
"surface": "blog-header-image",
"title": "Modern",
"order": 1,
"preview": "Bold gradients & geometric shapes"
}
]
}curl "https://www.pop-cam.com/api/presets?surface=nanobanana&includePrompt=false" \ -H "Authorization: Bearer CLERK_JWT"
/api/v1/nanobananaGenerate images with NanoBanana. Supports two modes: image-to-image (provide an image to transform) and text-to-image (provide only a prompt to generate from scratch). Both modes support synchronous and asynchronous (webhook) delivery.
| Parameter | Type | Description |
|---|---|---|
Authorizationrequired | string | Bearer pk_your_token |
Content-Typerequired | string | application/json |
| Parameter | Type | Description |
|---|---|---|
image | string | Base64 data URL for image-to-image mode. Format: data:image/png;base64,.... Omit for text-to-image. |
prompt | string | Generation prompt. Required for text-to-image when no presetId is provided. Optional for image-to-image. |
presetId | string | Preset ID from GET /api/presets. When provided, the backend resolves the prompt text. |
presetSource | string | Preset source from the catalog, such as system or custom. Snake case preset_source is also accepted. |
surface | string | Preset surface. Defaults to nanobanana. Snake case preset_id is also accepted for presetId. |
webhook_url | string | URL to POST results to when done. Enables async mode (returns HTTP 202). |
Returned when no webhook_url is provided. Use download_url to fetch the image — it is a presigned URL (1-hour expiry) that works even when the storage bucket is private.
{
"job_id": "a1b2c3d4-e5f6-...",
"image_url": "https://...r2.cloudflarestorage.com/generated/...",
"download_url": "https://...r2.cloudflarestorage.com/...?X-Amz-Signature=...",
"used_prompt": "...",
"credits_remaining": 42,
"mode": "image-to-image"
}Returned when webhook_url is provided. Results are POSTed to your URL.
{
"job_id": "a1b2c3d4-e5f6-...",
"status": "processing",
"message": "Your image is being generated. Results will be POSTed to your webhook_url."
}import requests
import base64
with open("photo.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
response = requests.post(
"https://www.pop-cam.com/api/v1/nanobanana",
headers={"Authorization": "Bearer pk_YOUR_TOKEN"},
json={
"image": f"data:image/png;base64,{b64}",
"prompt": "Enhance this photo with cinematic lighting and shallow depth of field"
}
)
data = response.json()
print(f"Download URL: {data['download_url']}")
print(f"Credits remaining: {data['credits_remaining']}")import fs from "fs";
const imageData = fs.readFileSync("photo.png");
const base64 = imageData.toString("base64");
const response = await fetch("https://www.pop-cam.com/api/v1/nanobanana", {
method: "POST",
headers: {
"Authorization": "Bearer pk_YOUR_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
image: `data:image/png;base64,${base64}`,
prompt: "Enhance this photo with cinematic lighting and shallow depth of field",
}),
});
const data = await response.json();
console.log("Download URL:", data.download_url);curl -X POST https://www.pop-cam.com/api/v1/nanobanana \
-H "Authorization: Bearer pk_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A photorealistic portrait of a man in a leather jacket standing on a city rooftop at golden hour, natural lighting, shallow depth of field"
}'{
"job_id": "a1b2c3d4-e5f6-...",
"image_url": "https://...r2.cloudflarestorage.com/generated/...",
"download_url": "https://...r2.cloudflarestorage.com/...?X-Amz-Signature=...",
"used_prompt": "A photorealistic portrait of a man in a leather jacket standing on a city rooftop at golden hour, natural lighting, shallow depth of field",
"credits_remaining": 41,
"mode": "text-to-image"
}curl -X POST https://www.pop-cam.com/api/v1/nanobanana \
-H "Authorization: Bearer pk_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"image": "data:image/png;base64,...",
"presetId": "system-preset-id",
"presetSource": "system",
"surface": "nanobanana"
}'Provide a webhook_url in your request to enable async mode. The API returns immediately with HTTP 202 and a job_id, then POSTs the result to your URL when generation completes.
Use download_url to fetch the generated image (presigned, 1-hour expiry).
{
"success": true,
"job_id": "a1b2c3d4-e5f6-...",
"image_url": "https://...r2.cloudflarestorage.com/generated/...",
"download_url": "https://...r2.cloudflarestorage.com/...?X-Amz-Signature=...",
"used_prompt": "...",
"credits_remaining": 41
}{
"success": false,
"job_id": "a1b2c3d4-e5f6-...",
"error": "Description of what went wrong"
}Delivery is attempted up to 3 times with exponential backoff (1s, 2s, 4s). Return a 2xx status to acknowledge receipt.
job_id for idempotency.These endpoints use Clerk session auth (cookie or JWT), not API tokens. For a UI, visit Developer Settings.
/api/v1/tokensList all API tokens (masked) for the authenticated user.
{
"tokens": [
{
"id": "uuid",
"name": "My Agent",
"token": "pk_...a1b2c3",
"createdAt": "2025-01-15T...",
"lastUsedAt": "2025-01-16T...",
"revokedAt": null
}
]
}/api/v1/tokensCreate a new API token. The full token is only returned in this response.
| Parameter | Type | Description |
|---|---|---|
name | string | Label for the token (e.g. "My Agent"). Defaults to "Default". |
/api/v1/tokens?id=TOKEN_IDRevoke a token. It immediately stops working for all requests.
Each tool below supports GET for its form configuration and POST for generation at /api/free-tools/<slug>. Generation requires a Clerk session cookie or Bearer JWT. The existing account-wide free pool applies, followed by 1 💎 per image.
POST accepts image (base64 image data URL) for photo tools or text (up to 1,200 characters) for text tools, plus optional styleId and custom. GET returns the supported style IDs and limits. Generation returns the existing photo-edit response: jobId, imageUrl, dataUrl, remaining, usedCredits and creditsRemaining.
Public tool suggestions: POST /api/free-tools/suggest with { "query": "a menu for my cafe" }. Queries are limited to 200 characters. The response contains tools (href and score) and mode (semantic or keyword). Suggestions use no 💎; keyword matching remains available during rate limits or provider failures.
These are the endpoints behind the free tools on pop-cam.com/free-tools and in the Pop-cam app. A signed-in Pop-cam account sends the browser session cookie, or the Pop-cam app's Clerk token as Authorization: Bearer. API tokens (pk_) are not accepted here.
payWithCredits: true. Without enough 💎 it gets 2 free generations a week (each comes back 7 days after it was used). One network (IP) gets at most 6 free generations a week, its accounts and signed-out browsers together. remaining in a response is the free generations left: the signed-out ones, or the account's this week. A free generation's image carries a small Pop-cam mark; one paid with 💎 doesn't. Agents and scripts should use Generate Image with an API token instead.Every generation gets a jobId (a UUID). It comes back in the response, and also in the error body when the generation fails (500, 502, 503 and the 422 CONTENT_REFUSED). Quote it when you report a problem. The stored image's file name is the same id.
Once a signed-out browser has used its free generations (counted by a cookie, and by its IP for 24 hours), every free tool generation endpoint answers with:
{
"error": "Sign in required",
"code": "SIGN_IN_REQUIRED",
"message": "You've used your free generations. Sign up free and get 2 credits, then 2 free generations every week."
}A signed-out generation must carry a Cloudflare Turnstile token from the tool's page, in the x-turnstile-token header. Without a valid one the endpoint answers 403 BOT_CHECK_FAILED. Signed-in requests are not checked.
/api/free-tools/notes-to-infographicTurn plain-text notes into a visually rich infographic image. Pass your notes and receive a downloadable PNG — perfect for summarizing meeting notes, study material, or data briefs.
| Parameter | Type | Description |
|---|---|---|
notesrequired | string | The text notes to visualize. Maximum 5,000 characters. |
style | string | Visual style of the poster. One of classic (default), swiss, or data. Unrecognized or omitted values fall back to classic. |
| Parameter | Type | Description |
|---|---|---|
classic | default | Balanced minimal poster — stat row, short notes, teal accent. |
swiss | option | International Typographic Style. Bold headline, one red accent, generous empty space. |
data | option | Big-number layout. Key figures set huge and stacked down the page. |
{
"jobId": "3f6c1a2e-8b4d-4f1e-9a7c-2d5e8f0b1c3a",
"imageUrl": "https://www.pop-cam.com/api/r2-image?key=generated%2Ffree-tools%2F3f6c1a2e-8b4d-4f1e-9a7c-2d5e8f0b1c3a.png&e=1794700800&s=...",
"dataUrl": "data:image/png;base64,...",
"style": "classic",
"remaining": 1
}| Parameter | Type | Description |
|---|---|---|
jobId | string | This generation's id. The stored file is named after it. |
imageUrl | string | Public URL of the stored infographic on CDN. |
dataUrl | string | Base64 data URL for immediate use without a second fetch. |
style | string | The style actually used — echoes back classic when the requested id was unrecognized. |
remaining | number | Free generations left: a signed-out browser's 1, across all free tools, never reset. Always 0 for an account, which pays with 💎. |
A signed-in request without payWithCredits: true:
{
"error": "Rate limit exceeded",
"message": "Each infographic costs 1 credit.",
"remaining": 0,
"creditCost": 1
}/api/free-tools/blog-header-imageGenerate a stunning blog header / feature image from a title and optional description. Choose from multiple visual styles. Returns a wide-format, publish-ready PNG — perfect for blog platforms, Medium, Dev.to, and social media Open Graph previews.
| Parameter | Type | Description |
|---|---|---|
titlerequired | string | The blog post title to display on the image. Maximum 300 characters. |
description | string | Optional topic context to guide the visual theme. Maximum 1,000 characters. Not rendered as text in the image. |
style | string | Visual style preset. One of: modern (default), illustration, tech, nature, abstract, minimal. |
presetId | string | Optional backend style preset ID from GET /api/presets?surface=blog-header-image. Preferred for new clients. |
presetSource | string | Use tool-style when sending a blog-header preset ID. |
{
"jobId": "3f6c1a2e-8b4d-4f1e-9a7c-2d5e8f0b1c3a",
"imageUrl": "https://www.pop-cam.com/api/r2-image?key=generated%2Ffree-tools%2F3f6c1a2e-8b4d-4f1e-9a7c-2d5e8f0b1c3a.png&e=1794700800&s=...",
"dataUrl": "data:image/png;base64,...",
"remaining": 1
}| Parameter | Type | Description |
|---|---|---|
jobId | string | This generation's id. The stored file is named after it. |
imageUrl | string | Public URL of the stored header image on CDN. |
dataUrl | string | Base64 data URL for immediate use without a second fetch. |
remaining | number | Free generations left: a signed-out browser's 1. Always 0 for an account, which pays with 💎. |
Calling from a script or an agent? Use Generate Image with an API token.
/api/free-tools/change-camera-angleReshoot an avatar from a new camera angle. Upload an image and either request a specific angle (low, high, Dutch tilt, profile, cowboy shot, etc.) or pass random to roll a different angle every call. Returns a new PNG of the same subject from a different camera perspective.
| Parameter | Type | Description |
|---|---|---|
imagerequired | string | Source avatar as a base64 data URL (data:image/png;base64,...). Max 8 MB. PNG, JPEG, or WEBP. |
angleId | string | Camera angle id. Pass random (default) for a different angle every request, or one of the catalog ids: low-angle, high-angle, birds-eye, worms-eye, dutch-angle, profile, three-quarter, over-shoulder, back-view, extreme-close-up, wide-shot, cowboy-shot. |
{
"jobId": "3f6c1a2e-8b4d-4f1e-9a7c-2d5e8f0b1c3a",
"imageUrl": "https://www.pop-cam.com/api/r2-image?key=generated%2Ffree-tools%2F3f6c1a2e-8b4d-4f1e-9a7c-2d5e8f0b1c3a.png&e=1794700800&s=...",
"dataUrl": "data:image/png;base64,...",
"angle": {
"id": "dutch-angle",
"label": "Dutch Angle",
"description": "Tilted — uneasy, dynamic"
},
"remaining": 1
}remaining is how many free generations are left: a signed-out browser's 1, across all free tools. An account pays 1 💎 per reframe.
/api/free-tools/change-camera-angleReturns the catalog of camera angles (id, label, emoji, description) so clients can render their own picker UI without hard-coding the list.
Calling from a script or an agent? Use Generate Image with an API token.
/api/free-tools/mascot-logoGenerate a minimal square mascot logo from a text description. Unlike the other free tools this one is preview-first: a signed-out browser's first preview is free and an account pays 1 💎 per logo, download included, and the response carries a watermarked preview plus a signed downloadToken. The clean, unwatermarked file is only available from the download endpoint below, which costs 1 credit and requires authentication.
| Parameter | Type | Description |
|---|---|---|
subjectrequired | string | What the mascot is, in plain words — "a sleepy owl", "a round robot with one wide visor". 2–160 characters. |
palette | string | Color family. One of terracotta (default), sage, denim, plum, ochre, cream, midnight, or random. |
colorMode | string | three (default) for two mascot colors plus a background, or two for a single mascot color with negative-space facial cutouts. |
{
"jobId": "3f6c1a2e-8b4d-4f1e-9a7c-2d5e8f0b1c3a",
"previewDataUrl": "data:image/png;base64,...",
"downloadToken": "eyJrIjoi...Qw.9f2c...",
"tokenExpiresAt": "2026-05-06T18:00:00.000Z",
"palette": "terracotta",
"colorMode": "three",
"remaining": 1,
"creditCost": 1
}previewDataUrl is a 768 px watermarked PNG. No R2 key or public URL for the clean asset is returned — the token is the only handle on it, and it expires after 6 hours.
/api/free-tools/mascot-logo/downloadRequires auth (Clerk cookie or Authorization: Bearer <jwt>). Charges 1 credit and returns the raw PNG bytes with Content-Disposition: attachment, not JSON. The credit is debited only after the file is successfully read from storage, and each unlocked logo is saved to the caller's gallery — unlocking the same token again is free. Read the remaining balance from the X-Credits-Remaining response header.
| Parameter | Type | Description |
|---|---|---|
tokenrequired | string | The downloadToken from the generate call. |
Failure modes: 401 not signed in (requiresAuth), 402 not enough credits (requiresCredits), 410 token expired, 502 storage read failed (no credit charged).
/api/free-tools/mascot-logoReturns the palette catalog, the color modes, the credit cost, and the number of free generations (freeUsesPerAccount, freeUsesSignedOut) so clients can build their own picker.
Calling from a script or an agent? Use Generate Image with an API token.
/api/free-tools/geometric-logo-makerDesign three logo candidates built only from compass circles and straight lines, delivered as vector SVG. Preview-first like Mascot Logo: each run (three candidates) is free for a signed-out browser's first run and 3 💎 for an account, downloads included; each candidate carries a watermarked preview, a fill-less guidesSvg overlay of the compass circles its curves were cut from, and a downloadToken. Takes 10–20 seconds.
| Parameter | Type | Description |
|---|---|---|
briefrequired | string | The subject and what the brand does — "a crane for a ceramics studio". 3–200 characters. |
style | string | One of kamon (default), modernist, monoline, bauhaus. |
{
"jobId": "3f6c1a2e-8b4d-4f1e-9a7c-2d5e8f0b1c3a",
"variants": [
{
"name": "Tsuru Maru Crest",
"concept": "A crane with spread wings inside a ring ...",
"previewDataUrl": "data:image/png;base64,...",
"guidesSvg": "<svg xmlns=...>...</svg>",
"downloadToken": "q1Vb...x9"
}
],
"previewDataUrl": "data:image/png;base64,...",
"downloadToken": "q1Vb...x9",
"tokenExpiresAt": "2026-10-27T18:00:00.000Z",
"style": "kamon",
"remaining": 1,
"creditCost": 1
}variants usually holds three candidates (fewer if one failed validation). The top-level previewDataUrl and downloadToken repeat the first one for single-result clients.
/api/free-tools/geometric-logo-maker/downloadRequires auth. The first download of a candidate charges 1 credit and saves it to the caller's gallery; later downloads of either format are free. Returns raw bytes with Content-Disposition: attachment. Same failure modes as Mascot Logo (401, 402, 410, 502).
| Parameter | Type | Description |
|---|---|---|
tokenrequired | string | A candidate's downloadToken. |
format | string | svg for the vector, png (default) for a 2048 px PNG. |
Calling from a script or an agent? Use Generate Image with an API token.
| Status | Meaning | Resolution |
|---|---|---|
400 | Bad Request | Missing or malformed image field. |
401 | Unauthorized | Invalid or revoked API token, or a signed-out free tool request after its 2 free generations. |
402 | Payment Required | Insufficient credits. Purchase more. |
429 | Too Many Requests | Out of 💎, or a Notes / Blog Header request without payWithCredits. Buy credits at /checkout. |
500 | Server Error | Retry after a short delay. |
All errors return JSON with an error field:
{
"error": "Human-readable error description"
}Machine-readable OpenAPI spec: /api/v1/docs