API overview

Plug the pipeline into your own tools.

The full promptFigure pipeline — LLM orchestration and prompt-engineering included — behind a simple HTTP API. Send a sentence, get a figure.

Balance & billing

• Top up from $1 in whole-dollar amounts; every $50 charged earns $1 bonus balance.
• Balance pays for API usage and can also be put toward any plan.
• Balance is non-withdrawable and non-transferable.
• API quota is billed separately from plan quotas — ideal for batch generation and automation.

Quick start

• Want to fill in parameters, see sample code build up live, and try a call right here? Open the API playground.
• Create a key in the console under "API keys" (starts with pf_; shown in full only once). Auth header: Authorization: Bearer <your key>.
• Endpoint: POST https://promptfigure.pages.dev/api/v1/generate with body { "prompt": "...", "model": "standard" | "premium" }; optionally pass refDataUrl with a PNG data URL (≤ 8MB) as a reference image.
• model=standard outputs 1K ($0.02/call), model=premium outputs 1K or 2K ($0.15/call, same price) — both include the full LLM pipeline; fees are deducted from balance in real time (402 when balance is too low).
• Optional ratio parameter sets the aspect ratio: 1:1 (default) / 3:2 / 2:3 / 16:9 / 9:16; invalid values fall back to 1:1.
• Response is JSON: { b64_json, size, ratio, model, charged, balance }; failed generations are auto-refunded (see the refunded field).
• Rate limits match your plan: Free 5 / Lite 10 / Plus 15 / Pro 40 / Ultra 80 RPM (429 when exceeded).

Use in Codex / Claude agents

The API is plain REST (not OpenAI-compatible), so any agent that can issue HTTP requests can use it directly. Paste the snippet below into the agent's instructions file (AGENTS.md / CLAUDE.md) and it will call promptFigure whenever a scientific figure is needed:

## promptFigure scientific figures
When a scientific chart, schematic, mechanism diagram or graphical abstract is needed, call the promptFigure API:
curl -s -X POST https://promptfigure.pages.dev/api/v1/generate \
  -H "Authorization: Bearer $PROMPTFIGURE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"<one English sentence naming every group/value/gene>","model":"premium"}'
The .b64_json field of the JSON response is a PNG image (base64). Decode and inspect it:
echo '<response>' | jq -r .b64_json | base64 -d > figure.png

Reference image (optional, for image-to-image edits or composition/style alignment):
Option 1 (recommended): if the reference is already online, just pass its link — no image-host upload, no download/base64 needed.
Papers' figures, GitHub raw files, CDN or self-hosted images all work. Add "refUrl":"<direct image URL>" to the body (PNG ≤ 8MB, fetched server-side).
Only if the image is not online yet, upload it to a free image host, tested working: x0.at (curl -F "[email protected]" https://x0.at, small files kept long-term)
or uguu.se (curl -F "files[][email protected]" https://uguu.se/upload.php, ~24h).
Key requirement: it must be a DIRECT image link — opening it in a browser shows the image itself (content-type image/png), not a web page;
image hosts change policies often — if refIgnored:true keeps appearing, switch hosts or use option 2.
Option 2: inline a local PNG as "refDataUrl":"data:image/png;base64,<...>" (≤ 8MB after base64),
e.g. DATA=$(base64 -w0 ref.png), then add "refDataUrl":"data:image/png;base64,$DATA" to the -d body.
The two fields are mutually exclusive; refDataUrl wins when both are sent.
If the response contains "refIgnored":true, the reference was missing/invalid/unreachable and was dropped (the call still bills); check and retry.

• Create the key in the console under "API keys" (starts with pf_, shown in full only once); store it in an agent environment variable such as PROMPTFIGURE_KEY.
• model=standard outputs a 1K draft ($0.02/call), model=premium outputs a 2K final ($0.15/call); failed generations are auto-refunded, and 402 means insufficient balance.
• Write the prompt in English and name every entity (groups, values, genes, conditions) — the server-side pipeline expands it into a publication-grade prompt automatically; you do not need to write long prompts yourself.
• Optional parameters: ratio (1:1 / 3:2 / 2:3 / 16:9 / 9:16) and a reference image via either refUrl (public direct image URL, fetched server-side; host on a free image host like x0.at / uguu.se first) or refDataUrl (PNG data URL, ≤ 8MB).

One-click install as an Agent skill (recommended)

Don't want to wire things up by hand? We ship a ready-made Agent Skill. Once installed, skill-capable AI apps (Claude Code / Claude Desktop / WorkBuddy, etc.) automatically handle signup, key creation and API calls:

• Download the skill pack: https://promptfigure.pages.dev/downloads/promptfigure-api.zip (includes INSTALL.md).
• Claude Code: unzip and place the promptfigure-api/ folder under ~/.claude/skills/.
• WorkBuddy / OpenClaw: place it under ~/.workbuddy/skills/.
• Claude Desktop: import the zip in Settings → Skills.
• Agents without a skill directory (Codex / Cursor / Cline): append the bundled SKILL.md to AGENTS.md / CLAUDE.md / your rules file.
• The skill is updated over time — re-download to upgrade; this page and the API docs remain the authoritative source.

Error codes & what to do