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'] 包含生成的图片

参考图生成

提供参考图来引导输出效果。每张参考图可以通过 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`
`model`	string	否	模型名称：`gemini-3-pro-image-preview`（默认）或 `gemini-3.1-flash-image-preview`
`prompt`	string	是	描述要生成图片的文本提示词
`referenceImages`	array	否	参考图列表，最多 14 张
`referenceImages[].fileData`	object	否	以 URL 形式提供的参考图
`referenceImages[].fileData.fileUri`	string	是	图片 URL（支持 `http`、`https`、`gs` 协议）
`referenceImages[].fileData.mimeType`	string	是	MIME 类型：`image/png`、`image/jpeg` 或 `image/webp`
`referenceImages[].inlineData`	object	否	以 base64 编码形式提供的参考图
`referenceImages[].inlineData.data`	string	是	Base64 编码的图片数据
`referenceImages[].inlineData.mimeType`	string	是	MIME 类型：`image/png`、`image/jpeg` 或 `image/webp`
`imageConfig`	object	否	图片输出配置
`imageConfig.imageSize`	string	否	输出分辨率：`1K`、`2K`（默认）或 `4K`
`imageConfig.aspectRatio`	string	否	宽高比（见下表）

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

支持的宽高比

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

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

模型对比

模型	优势	备注
`gemini-3-pro-image-preview`	更高质量，细节更丰富	默认模型
`gemini-3.1-flash-image-preview`	生成更快，支持更多宽高比	适合快速迭代

响应

响应以流式方式返回模型原始 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