AI 生图

通过 API 使用文本提示词生成 AI 图片，支持通过 URL 或 base64 编码提供参考图来引导生成效果。

生成图片

POST /v1/images/generation

根据文本提示词生成 AI 图片。可选提供参考图来引导输出风格或内容。响应以流式方式返回模型原始输出（包含 base64 图片数据的 JSON）。

基础生成

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",
    "prompt": "宁静的山间日落景色，湖面倒映着晚霞",
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    }
  }'

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',
      prompt: '宁静的山间日落景色，湖面倒映着晚霞',
      imageConfig: {
        aspectRatio: '16:9',
        imageSize: '2K',
      },
    }),
  },
)
const data = await response.json()
// data.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',
        'prompt': '宁静的山间日落景色，湖面倒映着晚霞',
        'imageConfig': {
            'aspectRatio': '16:9',
            'imageSize': '2K',
        },
    }
)
data = response.json()
# data['candidates'][0]['content']['parts'][0]['inlineData'] 包含生成的图片

使用 GPT-Image-2 时，将 provider 设为 "openai"，model 设为 "gpt-image-2" 即可，请求和响应格式完全一致。具体差异见下方模型对比。

参考图生成

提供参考图来引导输出效果。每张参考图可以通过 URL（fileData）或 base64 编码数据（inlineData）提供，同一请求中可以混合使用两种格式。

使用图片 URL

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",
    "prompt": "将这个场景转换为水彩画风格",
    "referenceImages": [
      {
        "fileData": {
          "fileUri": "https://example.com/my-photo.jpg",
          "mimeType": "image/jpeg"
        }
      }
    ],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "2K"
    }
  }'

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',
      prompt: '将这个场景转换为水彩画风格',
      referenceImages: [
        {
          fileData: {
            fileUri: 'https://example.com/my-photo.jpg',
            mimeType: 'image/jpeg',
          },
        },
      ],
      imageConfig: {
        aspectRatio: '1:1',
        imageSize: '2K',
      },
    }),
  },
)
const data = await response.json()

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',
        'prompt': '将这个场景转换为水彩画风格',
        'referenceImages': [
            {
                'fileData': {
                    'fileUri': 'https://example.com/my-photo.jpg',
                    'mimeType': 'image/jpeg',
                }
            }
        ],
        'imageConfig': {
            'aspectRatio': '1:1',
            'imageSize': '2K',
        },
    }
)
data = response.json()

使用 Base64 编码数据

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",
    "prompt": "将这张人像照片转换为卡通风格",
    "referenceImages": [
      {
        "inlineData": {
          "data": "<BASE64_ENCODED_IMAGE>",
          "mimeType": "image/png"
        }
      }
    ]
  }'

import { readFileSync } from 'fs'

const imageBase64 = readFileSync('reference.png').toString('base64')

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',
      prompt: '将这张人像照片转换为卡通风格',
      referenceImages: [
        {
          inlineData: {
            data: imageBase64,
            mimeType: 'image/png',
          },
        },
      ],
    }),
  },
)
const data = await response.json()

import os
import base64
import requests

with open('reference.png', 'rb') as f:
    image_base64 = base64.b64encode(f.read()).decode('utf-8')

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'provider': 'google',
        'prompt': '将这张人像照片转换为卡通风格',
        'referenceImages': [
            {
                'inlineData': {
                    'data': image_base64,
                    'mimeType': 'image/png',
                }
            }
        ],
    }
)
data = response.json()

请求参数

字段	类型	必填	说明
`provider`	string	是	模型提供商：`google` 或 `openai`
`model`	string	否	模型名称：`gemini-3-pro-image`（默认）、`gemini-3.1-flash-image` 或 `gpt-image-2`（需设置 `provider: "openai"`）
`prompt`	string	是	描述要生成图片的文本提示词
`referenceImages`	array	否	参考图列表。Gemini 模型最多 14 张，GPT-Image-2 最多 4 张
`referenceImages[].fileData`	object	否	以 URL 形式提供的参考图
`referenceImages[].fileData.fileUri`	string	是	图片 URL（支持 `http`、`https`、`gs` 协议）
`referenceImages[].fileData.mimeType`	string	是	MIME 类型：`image/png`、`image/jpeg`、`image/webp`、`image/heic` 或 `image/heif`
`referenceImages[].inlineData`	object	否	以 base64 编码形式提供的参考图
`referenceImages[].inlineData.data`	string	是	Base64 编码的图片数据
`referenceImages[].inlineData.mimeType`	string	是	MIME 类型：`image/png`、`image/jpeg`、`image/webp`、`image/heic` 或 `image/heif`
`imageConfig`	object	否	图片输出配置
`imageConfig.imageSize`	string	否	输出分辨率：`1K`、`2K`（默认）或 `4K`。GPT-Image-2 各档位积分消耗见分辨率档位
`imageConfig.aspectRatio`	string	否	宽高比（见下表）。GPT-Image-2 可省略此参数，由模型自动选择

referenceImages 中的每一项必须且仅能包含 fileData 或 inlineData 之一，不能同时提供。

支持的宽高比

比例	说明
`1:1`	正方形
`2:3`	竖版
`3:2`	横版
`3:4`	竖版
`4:3`	横版
`9:16`	竖屏 / 手机
`16:9`	宽屏
`21:9`	超宽屏

gemini-3.1-flash-image 模型额外支持 1:4、4:1、1:8、8:1 宽高比，默认的 gemini-3-pro-image 模型不支持这些比例。

分辨率档位

GPT-Image-2 按输出分辨率分档计费：

档位	清晰度	积分	限免
`1K`	标清	4	每用户 100 次
`2K`	高清	6	每用户 100 次
`4K`	超高清	10	无

模型对比

模型	优势	备注
`gemini-3-pro-image`	更高质量，细节更丰富	默认模型
`gemini-3.1-flash-image`	生成更快，支持更多宽高比	适合快速迭代
`gpt-image-2`	OpenAI 最新图像模型，提示词跟随度高	最多 4 张参考图，支持全部标准宽高比，可省略 `aspectRatio` 自动适配

NanoBanana Pro 免费额度

API Key 调用消耗的免费额度（freeUsages），和网页端、Labnana 是同一份账户级余额。账户可以通过注册、邀请、签到持续领取额度，再通过 API 消费。实时余额可通过 GET /v1/user/subscription 查询，见其 freeUsages 字段。

资源键	模型 + 尺寸	适用范围
`gemini-3-pro-image-relax-1k-2k`	`gemini-3-pro-image`，`1K` / `2K`	NanoBanana Pro relax，核心免费权益
`wan2.7-image`	Wan 2.7，`1K` / `2K`	赠送的免费额度
`gpt-image-2`	`gpt-image-2`，`1K` / `2K`	赠送的免费额度

当对应余额大于 0 时，1K/2K 请求会扣 1 次免费额度而非积分；余额降到 0 后，同一请求会回退到常规积分计费。

免费额度仅适用于 1K 和 2K 尺寸。4K 请求永远不会扣 freeUsages，始终按积分计费。

NanoBanana Pro relax 调用的执行方式取决于账户类型：

付费 / 充值账户（有效订阅、充值或购买积分包）即使在消费免费额度时，也走常规付费生成体验 —— 完整优先级、正常容量、正常回退。免费额度只改变计费方式（不扣积分），不会把你降级到限流通道。
纯免费账户（从未付费）的 NanoBanana Pro relax 走 PT-only、最低优先级的免费通道，有固定吞吐上限。高峰时请求可能排队，或返回可重试的繁忙 / 超时响应。此时不扣积分、不扣免费额度 —— 稍后重试即可（深夜出图更快）。

NanoBanana Pro 免费额度指的是可以通过合资格操作持续领取的额度，并非无限即时生成、无限并发，也不是无限的 OpenAPI 调用。纯免费 relax 通道为 PT-only，繁忙时不会回退到 shared/paygo 容量。

纯免费 relax 失败会返回机器可读的元数据，无需解析本地化文案即可识别：

reason（或 failReason）为 free_relax_busy 或 free_relax_timeout。
retryable 为 true。
freeUsageRolledBack 在免费额度回退完成后为 true。
userMessage 提供友好、可本地化的文案。

同步请求时该信息出现在错误响应中；异步请求时出现在失败任务详情中。free_relax_busy 和 free_relax_timeout 都应按「稍后重试，未扣任何费用」处理。

618 活动与免费额度是两回事：2026-06-18 至 2026-06-24（Asia/Shanghai）期间，有效的 Pro / Max 订阅用户限时一周获得 +50% 月度积分。该加赠是普通月度积分，不是 NanoBanana Pro 免费额度，也不是永久套餐升级。详见订阅 API。

响应

响应以流式方式返回模型原始 JSON 输出。成功响应包含 base64 编码的生成图片：

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

将 data 字段从 base64 解码即可获得图片文件。

频率限制与参考图模式

标准文本生图请求受用户级和全局频率限制约束。

参考图模式（使用 inlineData 的 referenceImages）受服务端资源管控，高峰期可能会被更严格地限流。如果收到 429 Too Many Requests 响应，请等待一段时间后重试。建议在客户端实现指数退避重试策略。

错误码

HTTP 状态码	含义
`400`	请求参数无效（如所选模型不支持该宽高比）
`402`	积分不足
`429`	频率限制 — 稍后重试
`500`	图片生成失败 — 请重试

On this page