拍图猫文档API 参考
POST /api/v1/generate 的完整参数、响应与计费
拍图猫提供一个同步出图接口：发一个请求，等它出完，一次性返回图片地址。适合脚本和服务端调用。第一次接入先看快速开始。
POST /api/v1/generate
Authorization: Bearer sk_你的密钥
Content-Type: application/json需要 generate:write 权限。单次请求最长 5 分钟，出 4 张 4K 可能要一两分钟，客户端超时别设太短。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 二选一 | 提示词，最长 4000 字符 |
ref_image_ids | string[] | 二选一 | 参考图 id，见参考图 |
model | string | 否 | 默认 auto，见模型 |
ratio | string | 否 | 1:1 / 3:4（默认）/ 4:5 / 16:9 / 9:16 |
resolution | string | 否 | 1K / 2K / 4K。不传用模型默认值 |
quality | string | 否 | low / medium（默认）/ high，只对 GPT 系模型有效 |
n | number | 否 | 1（默认）/ 2 / 4 |
session_id | string | 否 | 归到哪个会话，见会话 |
purpose_id | string | 否 | 用途，见用途 |
prompt 和 ref_image_ids 至少要有一个，可以同时有。
参数写错不会被悄悄忽略。 传了不认识的 model、模型不支持的 ratio、超过上限的参考图张数，都直接 400，不会替你换成默认值再返回成功。
模型
model | 比例 | 分辨率 | 质量 | 参考图上限 | 每张积分 | 状态 |
|---|---|---|---|---|---|---|
auto | — | — | — | — | 按实际选中的模型 | 默认 |
nano-banana-2 | 全部 | 1K / 2K / 4K，默认 2K | 无 | 14 | 12 / 16 / 23 | 稳定 |
gpt-image-2 | 全部 | 1K / 2K / 4K，默认 1K | low / medium / high | 16 | 按质量 5 / 15 / 50，每张参考图 +1 | 稳定 |
gpt-image-2.5 | 全部 | 同上 | 同上 | 16 | 同上 | 测试中 |
seedream-5-0-pro | 无 4:5 | 1K / 2K，默认 1K | 无 | 10 | 6 / 12 | 测试中 |
qwen-image-3.0-pro | 无 4:5 | 1K / 2K，默认 1K | 无 | 3 | 6 / 11 | 测试中 |
auto 的规则：默认 nano-banana-2；提示词要求画面出现文字（品牌名、标语、价格）时用 gpt-image-2；参考图张数超过首选模型上限时换另一个装得下的。响应里没有单独字段告诉你 Auto 选了谁，需要确定模型请显式传 model。
GPT 系模型的 quality 不传按 medium（15 积分）计。其他模型忽略 quality。
用途
purpose_id 决定在你的提示词之外附加哪套电商摄影规则。不传等于 free。
purpose_id | 含义 |
|---|---|
free | 自由出图，只按提示词来 |
main_white | 商品主图 |
detail | 细节图 |
buyer_show | 买家秀 |
pure_white | 白底无人 |
参考图
ref_image_ids 填图片 id。目前 API 能拿到的 id 只有一个来源：这个接口之前返回的 images[].id。网页上传的图暂时没有对外的 id，也没有上传接口。
id 必须属于当前账号。图片已被删除或清理时返回 400 reference_image_missing，不会静默跳过。图片保留规则见图片下载。
会话
每次生成归属一个会话。不传 session_id 就自动新建一个，标题叫「API 生成」，在网页侧栏「最近对话」里能看到。传上一次响应里的 session_id，可以把多次生成归到同一个会话里，方便在网页上回看。
传了不存在或不属于你的 session_id 返回 404 session_not_found。
响应
{
"ok": true,
"turn_id": "t_xxxxxxxxxx",
"session_id": "s_xxxxxxxxxx",
"credits_charged": 16,
"duration_ms": 18320,
"warnings": [],
"images": [
{
"id": "img_xxxxxxxx",
"filename": "xxxxxxxx.png",
"url": "/api/file/xxxxxxxx.png",
"width": 1536,
"height": 2048
}
]
}| 字段 | 说明 |
|---|---|
turn_id | 本次生成的 id |
session_id | 所属会话，下次可以传回来 |
credits_charged | 实际扣的积分。部分成功时已经是退过差额的数 |
duration_ms | 生成耗时 |
warnings | 上游没能照办的部分，见下 |
images[].id | 图片 id，可作为下一次的 ref_image_ids |
images[].url | 相对路径，带同一把密钥请求，见图片下载 |
images[].width / height | 实际像素 |
响应头里有 X-Request-Id，反馈问题时附上。
warnings
空数组 = 完全按你的请求出的图。非空要看一眼，它列的是「你选了但上游没能照办」的部分：
{ "type": "downgraded", "feature": "ratio", "details": "上游出的是 1024×1024（1.000），与请求的 3:4（0.750）不一致；图片按原样交付，未做任何处理。" }| 字段 | 说明 |
|---|---|
type | unsupported 上游根本不支持；downgraded 支持但给不到要的规格 |
feature | 哪一项：ratio / resolution / quality / n 等 |
details | 给人看的说明，跟随语言：网页按界面语言，API 按 Accept-Language，默认中文 |
要 4 张只出了 2 张也会出现在这里（feature: "n"），并按 2 张结算。
计费
- 请求通过校验后先预扣（按
n张估算），再调模型 - 整次失败：全退，接口返回
500 - 部分成功：按实际张数结算，差额自动退，
credits_charged是退过之后的数 - 余额不够：
402 insufficient_credits，不预扣，message里带需要多少和充值联系方式
新账号（注册未满 7 天）24 小时内最多消耗 2000 积分，超过返回 429 new_user_daily_limit。
错误
出错统一返回：
{
"error": {
"code": "invalid_model",
"message": "不支持的模型",
"request_id": "req_xxxxxxxxxxxxxxxxxxxx"
}
}这条接口常见的：
| 状态码 | code | 含义 |
|---|---|---|
400 | invalid_request 及各参数子码 | 参数不合法，完整列表见错误格式 |
401 | unauthorized / invalid_api_key | 没带密钥 / 密钥无效、已撤销或已过期 |
402 | insufficient_credits | 积分不够 |
403 | insufficient_scope | 密钥没有 generate:write |
404 | session_not_found | session_id 不存在或不属于你 |
429 | rate_limited / new_user_daily_limit | 密钥超过限额 / 新账号超过日消耗上限 |
500 | internal_error | 生成失败，积分已退回，请附 request_id 反馈 |
完整示例
curl -X POST https://paitumao.com/api/v1/generate \
-H "Authorization: Bearer sk_你的密钥" \
-H "Content-Type: application/json" \
-d '{
"prompt": "白底T恤主图，模特正面，柔和布光",
"model": "nano-banana-2",
"ratio": "3:4",
"resolution": "2K",
"n": 2,
"purpose_id": "main_white"
}'这一次预扣 32 积分（2K 每张 16，两张）。