ListenHubDocs
API 参考图片生成

图片生成

在 Nano Banana、GPT-Image、Seedream、Wan 2.7 模型系列上，通过文本提示词和参考图同步或异步生成图片。

图片生成把文本提示词——可选地由参考图引导——转化为一张或多张图片。四个系列共九个模型共用同一套请求 schema 和同一组接口；用 model 字段选择模型。

你可以用三种方式调用：

  • 同步 —— POST /v1/images/generation 阻塞到图片就绪，并在响应体中返回模型原始输出 （base64 图片数据）。
  • 异步 —— POST /v1/images/generation/async 立即返回 taskId，随后轮询 GET /v1/images/generation/tasks/{taskId} 获取托管图片 URL。
  • 先预估 —— POST /v1/images/generation/estimate-credits 返回积分成本以及账户是否可生成， 不消耗任何额度。

本页所有接口都使用 OpenAPI Base URL https://api.marswave.ai/openapi，并通过 Authorization: Bearer $LISTENHUB_API_KEY 请求头用 API Key 鉴权。在 listenhub.ai/settings/api-keys 创建密钥。

选择模型

先用下表挑选模型，再打开对应系列页面查看精确限制、注意事项和示例。

模型系列适用场景尺寸宽高比参考图上限
gpt-image-2 (默认)GPT-Image提示词遵循能力强，按尺寸固定计价1K, 2K, 4K10 种标准比例4
gpt-image-2.5-flareGPT-Image第二种 GPT-Image 风格，价格与限制相同1K, 2K, 4K10 种标准比例4
gpt-image-2.5-sunburstGPT-Image第三种 GPT-Image 风格，价格与限制相同1K, 2K, 4K10 种标准比例4
gpt-image-2-officialGPT-Image唯一会遵循 quality 的模型；按 token 计价1K, 2K, 4K10 种标准比例4
gemini-3-pro-imageNano Banana输出细节最丰富；Nano Banana Pro1K, 2K, 4K10 种标准比例14
gemini-3.1-flash-imageNano Banana生成更快更便宜；Nano Banana 系列中唯一接受 1:4 / 4:1 / 1:8 / 8:1 的档位1K, 2K, 4K全部 14 种14
seedream-5-0-proSeedream按坐标和色号做精准区域编辑1K, 2K全部 14 种10
wan2.7-imageWan 2.7在五种常见比例上的低成本生成1K, 2K5 种比例9
wan2.7-image-proWan 2.7同样的五种比例，支持 4K 输出1K, 2K, 4K5 种比例9

省略 model 时默认使用 gpt-image-2。10 种标准比例指 1:1、2:3、3:2、3:4、4:3、 4:5、5:4、9:16、16:9 和 21:9 —— 即除四种极端比例外的全部比例。完整规则见 宽高比。

Nano Banana

gemini-3-pro-image 与 gemini-3.1-flash-image：Google 主打细节和主打速度的两个模型，以及四种极端比例。

GPT-Image

gpt-image-2、2.5 Flare 与 Sunburst 变体，以及 GPT-Image-2 Pro —— 唯一会遵循 quality 的模型。

Seedream

seedream-5-0-pro：把坐标写进 prompt，编辑已有图片中指定的区域。

Wan 2.7

wan2.7-image 与 wan2.7-image-pro：五种比例，严格校验，Pro 档支持 4K。

调用流程

预估花费

用你打算生成时使用的同一份请求体调用 POST /v1/images/generation/estimate-credits。它返回 credits 和 canGenerate，不消耗任何额度。积分成本随模型和尺寸变化 —— 请从这个接口读取， 不要写死。

生成

调用 POST /v1/images/generation 阻塞到图片就绪，或调用 POST /v1/images/generation/async 立即拿到 taskId。

获取结果

同步接口在响应体中返回 base64 图片数据。异步接口会替你存储图片 —— 轮询 GET /v1/images/generation/tasks/{taskId} 直到 status 为 success，再读取托管的 images[].url。

请求参数

以下参数适用于 POST /v1/images/generation、POST /v1/images/generation/async 和 POST /v1/images/generation/estimate-credits —— 这三个接口共用同一套请求 schema。

字段类型必填说明
providerstring是¹模型厂商：google、openai、bytedance、alibaba 或 quotaflow
modelstring否模型名。默认 gpt-image-2。旧版 preview ID 会归一化为对应的 GA ID。详见 选择模型
promptstring是²待生成图片的文本描述
referenceImagesarray否用于引导生成的参考图。详见 参考图
referenceImages[].fileDataobject否以 URL 形式提供的参考图
referenceImages[].fileData.fileUristring是图片 URL —— scheme 必须为 http、https 或 gs
referenceImages[].fileData.mimeTypestring是MIME 类型：image/png、image/jpeg、image/webp、image/heic 或 image/heif
referenceImages[].inlineDataobject否以 base64 编码数据形式提供的参考图
referenceImages[].inlineData.datastring是base64 编码的图片数据
referenceImages[].inlineData.mimeTypestring是MIME 类型：与 fileData.mimeType 相同的五个取值
imageConfigobject否图片输出配置。默认 { "imageSize": "2K" }
imageConfig.imageSizestring否输出分辨率：1K、2K（默认）或 4K，受各模型限制约束
imageConfig.aspectRatiostring否宽高比。各系列的默认规则见 宽高比
imageConfig.qualitystring否low、medium 或 high。仅 gpt-image-2-official 会遵循；其他模型一律忽略

¹ provider 在两个生成接口上必填，在 estimate-credits 上可选。 ² prompt 在两个生成接口上必填；在 estimate-credits 上可为空或省略（它只影响输入 token 预估）。

referenceImages 中的每一项必须至少带上 fileData 或 inlineData 之一。请只发送其中一个 —— 校验允许一项同时带两者，但此时行为未定义。

provider 会被校验，但不用于路由 —— 上游完全由 model 决定。请像本组页面的所有示例那样， 发送与模型匹配的厂商值，让请求保持可读；但填得不匹配也不会改变实际运行的模型。

向 gpt-image-2、gpt-image-2.5-flare 或 gpt-image-2.5-sunburst 传 quality 不会报错 —— 该值会被丢弃，estimate-credits 返回警告 quality_ignored_for_gpt_image_2_lite。 只有 gpt-image-2-official 会按请求的质量渲染。详见 GPT-Image。

宽高比

整个模型目录共有 14 种比例。其中 10 种是标准比例，大多数模型都接受；4 种是极端比例， 仅 gemini-3.1-flash-image 和 seedream-5-0-pro 接受。

比例说明类别
1:1正方形标准
2:3竖向标准
3:2横向标准
3:4竖向标准
4:3横向标准
4:5竖向标准
5:4横向标准
9:16竖屏 / 移动端标准
16:9宽屏标准
21:9超宽屏标准
1:4窄竖向极端
4:1宽横向极端
1:8极窄竖向极端
8:1全景极端

imageConfig.aspectRatio 在 schema 层带有默认值 1:1。只要你发送了 imageConfig 对象却不带 aspectRatio，任何模型都会给你一张正方形图片 —— 下面的分系列行为只在你完全省略 imageConfig 时才生效，因为它自身的对象默认值是 { "imageSize": "2K" }，不会设置比例。

在上面的 schema 默认值没有替你填上比例的前提下，aspectRatio 的解析方式如下：

系列仍未设置时不支持时
Nano Banana解析为 1:1400，code: 29003
GPT-Image不设置 —— 由模型按提示词选择比例400，code: 26019，消息中给出支持的比例列表
Seedream不设置接受 —— Seedream 校验的是尺寸，不是比例
Wan 2.7不设置400，code: 26019，消息中给出支持的比例列表

图片尺寸

imageConfig.imageSize 接受 1K、2K（默认）和 4K。尺寸越大消耗的积分越多。

模型1K2K4K
全部 GPT-Image 模型是是是
两个 Nano Banana 模型是是是
seedream-5-0-pro是是400
wan2.7-image是是400
wan2.7-image-pro是是仅支持文生图 —— 带参考图时返回 400

请勿写死积分成本 —— 调用 estimate-credits 获取你所用模型、尺寸和比例的精确数值。

参考图

参考图用于引导生成。每张参考图要么以 URL（fileData）提供，要么以 base64（inlineData）提供， 不能同时给两者，并且数组长度不得超过所选模型的上限。

系列参考图上限
Nano Banana14（schema 上限）
GPT-Image4
Seedream10
Wan 2.79

schema 对所有模型都将 referenceImages 限制为最多 14 项。上限更严的系列会以 400 拒绝超出的 部分，并在消息中给出该上限。fileData 和 inlineData 接受的 MIME 类型均为 image/png、 image/jpeg、image/webp、image/heic 和 image/heif。

三个图片接口接受的 JSON 请求体上限为 25MB —— 是平台默认值的四倍，因为 base64 inlineData 必须装得进去。base64 会让文件膨胀约三分之一，所以内联图片的原始字节总量请控制在约 18MB 以内， 或者改用 fileData 传 URL。

生成图片（同步）

POST /v1/images/generation

生成图片并阻塞到图片就绪。响应体是模型原始输出 —— 包含 base64 图片数据的 JSON，不是标准的 { code, message, data } 信封。详见 响应格式。

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "An astronaut riding a horse on Mars, photorealistic",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "16:9"
    }
  }'
const response = await fetch(
  'https://api.marswave.ai/openapi/v1/images/generation',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      provider: 'google',
      model: 'gemini-3-pro-image',
      prompt: 'An astronaut riding a horse on Mars, photorealistic',
      imageConfig: { imageSize: '2K', aspectRatio: '16:9' },
    }),
  },
)
const result = await response.json()
const image = result.candidates[0].content.parts[0].inlineData
import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'provider': 'google',
        'model': 'gemini-3-pro-image',
        'prompt': 'An astronaut riding a horse on Mars, photorealistic',
        'imageConfig': {'imageSize': '2K', 'aspectRatio': '16:9'},
    },
)
result = response.json()
image = result['candidates'][0]['content']['parts'][0]['inlineData']

携带参考图

参考图在每个接口上的用法都相同。图片已有托管地址时用 fileData，图片字节在内存中时用 inlineData。

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "Redraw this character in a watercolor style",
    "referenceImages": [
      {
        "fileData": {
          "fileUri": "https://example.com/character.png",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
  }'
curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "Redraw this character in a watercolor style",
    "referenceImages": [
      {
        "inlineData": {
          "data": "'"$(base64 -w0 character.png)"'",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
  }'

携带 base64 参考图的请求受一套独立且更严格的限流约束。遇到 429 时，读取 Retry-After 响应头并退避后再重试。

异步生成

对于耗时较长或高分辨率的任务，提交任务后轮询结果，而不是长时间占用一个请求连接。

创建异步任务

POST /v1/images/generation/async

请求体与同步接口相同。立即返回 202 和一个 taskId；生成在后台进行，产出的图片会以托管 URL 形式持久化。

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/async" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "An astronaut riding a horse on Mars, photorealistic",
    "imageConfig": { "imageSize": "4K", "aspectRatio": "16:9" }
  }'

响应（202）：

{
  "code": 0,
  "message": "",
  "data": { "taskId": "65f0...", "status": "pending" }
}

获取单个任务

GET /v1/images/generation/tasks/{taskId}

轮询单个任务的状态和结果。status 取值为 pending、generating、success 或 fail。 成功时 images 中是托管的结果 URL。

curl "https://api.marswave.ai/openapi/v1/images/generation/tasks/65f0abc..." \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"
{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "65f0abc...",
    "status": "success",
    "images": [{ "url": "https://.../0.png", "mimeType": "image/png" }],
    "createdAt": 1750000000000,
    "completedAt": 1750000020000
  }
}
字段类型说明
taskIdstring任务标识
statusstringpending、generating、success 或 fail
imagesarray成功时返回；每一项为 { url, mimeType }
failMsgstringstatus 为 fail 时的失败信息
createdAtnumber创建时间（epoch 毫秒）
completedAtnumber完成时间（epoch 毫秒），任务结束后返回

列出任务

GET /v1/images/generation/tasks

列出你的图片任务，最新的在前。

查询参数类型默认值说明
pagenumber1页码，最小 1
pageSizenumber20每页条数，1–100
statusstring—按 pending、generating、success 或 fail 过滤
curl "https://api.marswave.ai/openapi/v1/images/generation/tasks?page=1&pageSize=20&status=success" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"
{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "taskId": "65f0...",
        "status": "success",
        "images": [],
        "createdAt": 1750000000000,
        "completedAt": 1750000020000
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

后台任务若停留在 pending 或 generating 超过 30 分钟，会被扫描置为 fail 并附带超时 failMsg。对超过该时长仍处于非终态的任务，按失败处理并重试。

预估积分

POST /v1/images/generation/estimate-credits

返回给定配置的积分成本以及账户余额是否足够，不消耗积分、也不调用模型。接受与生成接口相同的 请求体；这里 provider 和 prompt 为可选。

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/estimate-credits" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "1:1"
    }
  }'
const response = await fetch(
  'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-image-2',
      imageConfig: { imageSize: '2K', aspectRatio: '1:1' },
    }),
  },
)
const { data } = await response.json()
console.log(data.credits, data.canGenerate)
import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'model': 'gpt-image-2',
        'imageConfig': {'imageSize': '2K', 'aspectRatio': '1:1'},
    },
)
data = response.json()['data']
print(data['credits'], data['canGenerate'])

预估响应

包裹在标准信封中。data 对象：

字段类型说明
modelstring用于预估的归一化 GA 模型 ID
imageSizestring解析出的输出尺寸
aspectRatiostring解析出的宽高比（模型自动选择时不返回）
qualitystring解析出的质量（不适用时不返回）
pixelsobject解析成功时为 { "width": number, "height": number, "size": "WxH" }
creditsnumber该配置将消耗的积分
canGenerateboolean账户有效积分余额是否足够
requiresSubscriptionboolean仅 gpt-image-2-official 在 4K 或 quality: high 时为 true
pricingobject定价元数据：pricingVersion、mode（token-estimate 或 fixed）及费率输入
warningsarray提示性字符串，如 quality_ignored_for_gpt_image_2_lite
{
  "code": 0,
  "message": "",
  "data": {
    "model": "gpt-image-2",
    "imageSize": "2K",
    "aspectRatio": "1:1",
    "credits": 6,
    "canGenerate": true,
    "requiresSubscription": false,
    "pricing": { "pricingVersion": "gpt-image-2-lite-fixed-2026-06-15", "mode": "fixed" },
    "warnings": []
  }
}

大多数模型按尺寸固定积分计价（mode: "fixed"）。gpt-image-2-official 按预估 token 计价 （mode: "token-estimate"），因此它的成本会随提示词长度、输出尺寸、请求的质量以及参考图 数量变化（通过 API 调用时每张参考图按统一费率计入）。

credits 始终是该配置的积分价格。它不会扣除免费额度 —— 账户仍有额度时，一次 1K 或 2K 请求会按全价预估，实际却不花钱。如果你需要展示账户真正会付的价格，请自己读取 freeUsages。

免费生成额度

API key 调用与 ListenHub、Labnana 应用共享同一个账户级免费额度（freeUsages）余额。你通过注册、 邀请和签到赚取额度，再通过 API 消费。用 GET /v1/user/subscription 查询实时余额，读取其 freeUsages 映射。

当匹配的余额大于 0 时，一次 1K 或 2K 请求会消费一次免费生成而非积分。余额降到 0 后， 同一请求会回退到正常积分计费。

免费额度资源覆盖的模型
gemini-3-pro-image-relax-1k-2kgemini-3-pro-image
gemini-3.1-flash-imagegemini-3.1-flash-image
gpt-image-2gpt-image-2
gpt-image-2.5gpt-image-2.5-flare、gpt-image-2.5-sunburst
seedream-5-0-proseedream-5-0-pro
wan2.7-imagewan2.7-image

免费额度仅适用于 1K 和 2K 尺寸 —— 4K 请求永远不会动用 freeUsages，始终按积分 计费。gpt-image-2-official 和 wan2.7-image-pro 在任何尺寸下都没有免费额度。

gemini-3-pro-image 是唯一的免费额度跑在独立执行通道上的模型，并带有可供分支判断的专属失败 元数据 —— 见 Nano Banana → relax 通道。

响应格式

接口是否包裹信封？响应体
POST /v1/images/generation否 —— 模型原始 JSONbase64 图片数据（见下）
POST /v1/images/generation/async是{ taskId, status }
POST /v1/images/generation/estimate-credits是预估对象
GET /v1/images/generation/tasks是分页 { items, page, pageSize, total }
GET /v1/images/generation/tasks/{taskId}是任务对象

同步接口直接返回模型原始输出。成功的响应体以 base64 数据包含生成的图片：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_ENCODED_IMAGE>"
            }
          }
        ]
      }
    }
  ]
}

将 data 字段从 base64 解码即可得到图片文件。异步路径会替你持久化图片，并在任务对象上返回 托管 url —— 无需做 base64 解码。

错误码

错误使用标准信封并带非零 code；对同步接口，则是 免费生成额度 中描述的原始错误体。

这些路由会把所有业务错误归一化为 HTTP 400。积分不足是带 code: 26004 的 400，不是 402 —— 请按信封里的 code 分支判断，而不是 HTTP 状态码。429 是唯一自带含义的状态码。 例外是同步的 free-relax 失败响应体：它是原始格式而非信封，带的是 errno 而不是 code。

HTTP 状态码code含义
40029003参数无效 —— 模型不接受的尺寸或参考图数量，或 Nano Banana 系列不接受的比例
40026019GPT-Image 或 Wan 2.7 上不支持的宽高比
40026004积分不足
40023016需要订阅 —— 账户没有生效中的套餐，却用 gpt-image-2-official 请求 4K 或 quality: high。请先看预估结果里的 requiresSubscription
429—触发限流或服务繁忙 —— 读取 Retry-After 后退避重试

比例被拒绝时返回的错误码并不统一：Nano Banana 抛 29003，GPT-Image 和 Wan 2.7 抛 26019。 如果你要识别「这个模型不支持该比例」，两个码都得判。

两个生成接口都受按用户和全局的限流约束。携带 base64 参考图（inlineData）的请求受一套独立且 更严格的限制，高峰期可能最先被限流。estimate-credits 不受限流约束。

相关

订阅与积分

查询积分与免费额度余额

AI 视频

把生成的图片转成视频

图片生成 skill

从 AI agent 而非 HTTP 调用这些模型

PixVerse 视频

调用 PixVerse 的九种能力生成 AI 视频——文生视频、图生视频、转场、融合、风格化、模仿、对口型，以及营销 Agent。

Nano Banana

Nano Banana Pro 与 Flash 的限制、四种极端宽高比，以及免费 relax 通道。

本页内容

选择模型调用流程预估花费生成获取结果请求参数宽高比图片尺寸参考图生成图片（同步）携带参考图异步生成创建异步任务获取单个任务列出任务预估积分预估响应免费生成额度响应格式错误码相关