API playground
Fill params, build sample code, try it live.
Fill in the parameters on the left and the request sample in each language updates on the right — copy it and run. You can also click "Send request" to try one live call and see the returned figure.
Endpoint & auth
POST https://promptfigure.pages.dev/api/v1/generate
Authorization: Bearer pf_... (create in the console under "API keys"; shown in full only once)
Content-Type: application/jsonRequest parameters
| Param | Type | Required | Description |
|---|---|---|---|
| prompt | string | Yes | One-sentence description (any language; name every entity), ≤ 8000 chars; the server-side pipeline expands it into a publication-grade prompt automatically |
| model | string | No | standard (default, $0.02/call, 1K output) or premium ($0.15/call, 1K and 2K at the same price) |
| size | string | No | premium only: 1K or 2K, default 2K; standard always outputs 1K |
| ratio | string | No | Aspect ratio: 1:1 (default) / 3:2 / 2:3 / 16:9 / 9:16; invalid values fall back to 1:1 |
| refDataUrl | string | No | PNG reference image as a data URL (data:image/png;base64,…, ≤ 8MB after base64). PNG data URLs only. For image-to-image edits and composition/style alignment. Invalid references are ignored and the response carries refIgnored: true |
| refUrl | string | No | Public URL of the reference image (http/https, PNG ≤ 8MB, fetched server-side; must be a direct image link that renders the image itself with content-type image/png — not a web page). Mutually exclusive with refDataUrl — refDataUrl wins when both are sent. No host? Upload to a free image host first, tested working: x0.at (curl -F "file=@ref.png" https://x0.at) or uguu.se (~24h) |
Auto-refund on failure: when generation fails (502) or rate limiting kicks in (429), the fee is refunded to your balance. On 502 the detail field explains the failure and refunded shows the amount; on 429 the limit field is your tier's RPM.
Response fields
| Field | Type | Description |
|---|---|---|
| b64_json | string | PNG image (base64); decode with base64 -d to get the file |
| size | string | Actual output tier: 1K / 2K |
| ratio | string | Actual aspect ratio |
| model | string | Tier used: standard / premium |
| provider | string | Image channel that served the request |
| crafted | boolean | Whether the LLM pipeline ran (always true on success) |
| refIgnored | boolean | Present only when a reference (refDataUrl/refUrl) was sent but missing, invalid or unreachable: true = the reference was dropped (the call still generates text-to-image and bills normally) |
| charged | number | Fee charged for this call (USD) |
| balance | number | Balance after the charge |
Error codes
| HTTP | error | Meaning | What to do |
|---|---|---|---|
| 400 | prompt_required / prompt_too_long | Missing prompt, or over 8000 chars | Fix the prompt in the request body and retry |
| 401 | invalid_api_key | Key invalid or revoked | Create a new key in the console under "API keys" |
| 402 | insufficient_balance | Insufficient balance (response includes required and balance) | Top up in the console (from $1, whole-dollar amounts) and retry |
| 429 | rate_limited | RPM exceeded (Free 5 / Lite 10 / Plus 15 / Pro 40 / Ultra 80, shared per-minute window with the web app) | Retry serially with 1s+ gaps; the fee is auto-refunded |
| 502 | generation_failed | Generation failed | Fee auto-refunded; check the detail field and retry |