API 调试台

填参数、生成示例代码、在线试跑。

在左侧填好参数，右侧实时生成对应语言的请求示例，复制即可运行；也可以直接点「发送请求」在线试跑一次，看真实返回的图。

POST https://promptfigure.pages.dev/api/v1/generate
Authorization: Bearer pf_...   （控制台「API 密钥」创建，明文只显示一次）
Content-Type: application/json

参数	类型	必填	说明
prompt	string	是	一句话描述（中英均可，建议写全实体名称），≤ 8000 字符；服务端管线自动扩写成出版级提示词，无需自己写长 prompt
model	string	否	standard（默认，$0.02/次，1K 出图）或 premium（$0.15/次，1K 与 2K 同价）
size	string	否	仅 premium 生效：1K 或 2K，默认 2K；standard 恒为 1K
ratio	string	否	画面比例：1:1（默认）/ 3:2 / 2:3 / 16:9 / 9:16，非法值回落 1:1
refDataUrl	string	否	PNG 参考图 data URL（data:image/png;base64,…，base64 后 ≤ 8MB），仅支持 PNG data URL；用于以图改图、构图/风格对齐。非法时忽略并在响应返回 refIgnored: true
refUrl	string	否	公网参考图直链（http/https，PNG ≤ 8MB，服务器代取；必须是图片直链——浏览器打开直接显示图片，content-type 为 image/png，网页地址不算）；与 refDataUrl 二选一，同时传时 refDataUrl 优先。没有图床可先传免费图床拿直链，实测可用：x0.at（curl -F "file=@ref.png" https://x0.at）或 uguu.se（约 24h）

失败自动退款：生成失败（502）或触发限速（429）时，本次扣费都按原路退回余额。502 响应的 detail 说明失败原因、refunded 标明退还金额；429 响应的 limit 是当前档位 RPM。

字段	类型	说明
b64_json	string	PNG 图像（base64 编码），base64 -d 解码即得图片文件
size	string	实际出图档位：1K / 2K
ratio	string	实际画面比例
model	string	本次档位：standard / premium
provider	string	实际服务的生图通道
crafted	boolean	是否经过 LLM 编排管线（正常恒为 true）
refIgnored	boolean	仅当传了参考图（refDataUrl/refUrl）但缺失、非法或拉取失败时出现：true = 参考图已被忽略（当次按纯文生图生成并正常计费）
charged	number	本次扣费额（美元）
balance	number	扣费后余额

HTTP	error	含义	处置
400	prompt_required / prompt_too_long	缺少 prompt，或超过 8000 字符	检查请求体里的 prompt 后重试
401	invalid_api_key	密钥无效或已吊销	到控制台「API 密钥」换新 key
402	insufficient_balance	余额不足（响应附 required 与 balance）	控制台充值（$1 起，整数金额）后重试
429	rate_limited	超 RPM（免费 5 / Lite 10 / Plus 15 / Pro 40 / Ultra 80，与网页端共享同一分钟窗口）	串行重试，间隔 1s 以上；本次扣费已自动退回余额
502	generation_failed	生成失败	已自动原路退款；检查响应 detail 后重试