AI 生图 · 调用文档

使用 Image 2 与 Nano Banana Pro 生成图片，支持文生图、单参考图和最多 14 张参考图。

AI 生图提供 Image 2 与 Nano Banana Pro 两个模型。每个模型只保留 1K、2K、4K 三个常用档位；文生图、单参考图和多参考图同价。

生成任务为异步调用。提交后轮询任务状态，图片成功生成并转存到 Firefly 后才扣积分；参数错误、鉴权失败、余额不足或生成失败都不扣。

三步开始

注册：打开 /sign-up 注册，注册即送体验积分。
创建 API Key：到 /settings/apikeys 创建，形如 sk-xxxxxxxx。
选择档位：从下面 6 个产品码中选择一个并提交任务。

API Key 等于账户凭证，不要外泄或提交到代码仓库。泄露后请立即删除并重建。

六个固定档位

产品码	模型	清晰度	积分/张
`image2_1k`	Image 2	1K	20
`image2_2k`	Image 2	2K	39
`image2_4k`	Image 2	4K	59
`nano_banana_pro_1k`	Nano Banana Pro	1K	69
`nano_banana_pro_2k`	Nano Banana Pro	2K	99
`nano_banana_pro_4k`	Nano Banana Pro	4K	199

查询当前可用档位、画幅和上传限制：

curl 'https://firefly.qwjxqn.xyz/v1/images/capabilities'

1. 上传本地参考图

已有公网图片链接时可以跳过此步。上传接口支持 JPG、PNG、WebP，每张不超过 10MB；每次请求上传一张。

curl -X POST 'https://firefly.qwjxqn.xyz/v1/images/references' \
  -H 'X-API-Key: sk-你的key' \
  -F 'file=@./reference.png'

也可以直接发送图片二进制：

curl -X POST 'https://firefly.qwjxqn.xyz/v1/images/references' \
  -H 'X-API-Key: sk-你的key' \
  -H 'Content-Type: image/png' \
  --data-binary '@./reference.png'

成功返回 Firefly 公网链接：

{
  "code": 0,
  "msg": "成功",
  "request_id": "img-upload-...",
  "data": {
    "url": "https://firefly.qwjxqn.xyz/media/image_ref_....png",
    "bytes": 1331646,
    "content_type": "image/png"
  }
}

2. 提交生成任务

文生图

curl -X POST 'https://firefly.qwjxqn.xyz/v1/images/generations' \
  -H 'X-API-Key: sk-你的key' \
  -H 'Idempotency-Key: poster-20260728-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_code": "image2_1k",
    "prompt": "明亮白色摄影棚里的青绿色玻璃棱镜，1:1 方形，无文字"
  }'

单张或多张参考图

把上传接口返回的链接，或你自己的公网图片链接，放进 reference_images。最多 14 张。

curl -X POST 'https://firefly.qwjxqn.xyz/v1/images/generations' \
  -H 'X-API-Key: sk-你的key' \
  -H 'Idempotency-Key: poster-20260728-002' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_code": "nano_banana_pro_2k",
    "prompt": "融合两张参考图，保留第一张的商品主体与第二张的配色，生成 9:16 竖版海报，不要文字",
    "reference_images": [
      "https://firefly.qwjxqn.xyz/media/image_ref_aaa.png",
      "https://firefly.qwjxqn.xyz/media/image_ref_bbb.png"
    ]
  }'

成功提交返回 HTTP 202：

{
  "code": 0,
  "msg": "成功",
  "request_id": "img-...",
  "data": {
    "task_id": "30f86a9e-...",
    "status": "processing",
    "product_code": "nano_banana_pro_2k",
    "model": "nano-banana-pro",
    "resolution": "2K",
    "aspect_ratio": "9:16",
    "reference_count": 2,
    "credits_price": 99,
    "credits_charged": 0,
    "output": []
  }
}

请求参数

参数	必填	说明
`product_code`	推荐	六个固定产品码之一
`model` + `resolution`	与产品码二选一	例如 `image-2` + `2K`
`prompt`	是	1–4000 字符
`reference_images`	否	参考图公网链接数组，最多 14 张
`aspect_ratio`	否	`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`

未传 aspect_ratio 时，系统会识别提示词中的比例，以及“横版”“竖版”“方形”等表达；仍未识别时默认 1:1。

建议每次提交携带唯一的 Idempotency-Key。网络重试时复用同一个值，避免重复生成和重复上游成本。

3. 查询并下载

curl 'https://firefly.qwjxqn.xyz/v1/images/tasks/30f86a9e-...' \
  -H 'X-API-Key: sk-你的key'

生成中返回 status: "processing"。成功后返回：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "task_id": "30f86a9e-...",
    "status": "succeeded",
    "credits_price": 99,
    "credits_charged": 99,
    "balance": 901,
    "output": [
      {
        "url": "https://firefly.qwjxqn.xyz/media/image_output_....png",
        "expires_at": "2026-08-04T..."
      }
    ]
  }
}

credits_charged 只在本次查询实际完成扣费时显示档位价格；后续重复查询同一任务为 0，不会再次扣费。结果链接保证保留 7 天，请及时下载或转存。

常见状态码

HTTP	含义	是否扣费
`400`	参数、参考图格式或参考图链接无效	否
`401`	API Key 缺失或无效	否
`402`	余额不足	否
`404`	任务不存在，或任务不属于当前 API Key	否
`429`	请求过快	否
`502`	两条生成通道均失败或暂时不可用	否
`503`	Firefly 计费或存储暂时不可用	否

接入建议

生成通常需要几十秒到数分钟，请轮询任务接口，不要把提交请求当作同步生成。
每 3–5 秒查询一次即可，不要高频轮询。
外部参考图可能过期或禁止访问；重要素材优先使用 Firefly 上传接口。
一张或多张参考图不会提高 Firefly 档位价格，但参考图越多，模型越可能需要更清晰的提示词说明各图用途。

AI 生图 · 调用文档

On this page