图像生成

Rivus AI 支持两类 Gemini 图像生成模型：

Imagen 系列（如 imagen-3.0-generate-001）：专业文生图模型，使用 /gemini/v1beta/models/{model}:predict + instances 协议
Gemini 图像模型（如 gemini-2.5-flash-image-preview、gemini-3-pro-image-preview）：多模态推理 + 图像生成，推荐通过 OpenAI 风格 /v1/images/generations 调用，由网关转换为 generateContent + imageConfig

Gemini 3 Pro Image 系列模型结合了 Gemini 3 的推理能力与高保真图像生成，适合需要理解复杂提示词的场景。

Imagen 系列：/gemini/v1beta/models/:predict

POST /gemini/v1beta/models/{model}:predict 用于调用 Imagen 系列模型生成图像，支持多种宽高比和批量生成。

基础请求

curl -X POST "$BASE_URL/gemini/v1beta/models/imagen-3.0-generate-001:predict" \
  -H "x-goog-api-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{
      "prompt": "a panda reading a book in the library, cinematic lighting"
    }],
    "parameters": {
      "aspectRatio": "1:1",
      "sampleCount": 1
    }
  }'

响应示例

{
  "predictions": [
    {
      "bytesBase64Encoded": "<BASE64_IMAGE_DATA>",
      "mimeType": "image/png"
    }
  ]
}

宽高比设置

通过 aspectRatio 参数控制图像比例：

{
  "instances": [{"prompt": "sunset over mountains"}],
  "parameters": {
    "aspectRatio": "16:9"
  }
}

支持的宽高比：

1:1：正方形（1024x1024）
16:9：横向宽屏（1792x1024）
9:16：竖向（1024x1792）
4:3：传统横向（1536x1152）
3:4：传统竖向（1152x1536）

批量生成

通过 sampleCount 参数一次生成多张图片：

curl -X POST "$BASE_URL/gemini/v1beta/models/imagen-3.0-generate-001:predict" \
  -H "x-goog-api-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{
      "prompt": "futuristic cityscape at night"
    }],
    "parameters": {
      "aspectRatio": "16:9",
      "sampleCount": 4
    }
  }'

sampleCount 最大值取决于模型限制，通常为 4。生成的每张图片都会单独计费。

人物生成控制

通过 personGeneration 参数控制是否允许生成人物：

{
  "instances": [{"prompt": "portrait of a scientist"}],
  "parameters": {
    "personGeneration": "allow_adult"
  }
}

可选值：

allow_adult：允许生成成年人物
dont_allow：不允许生成人物

负面提示词

使用 negativePrompt 排除不想要的元素：

{
  "instances": [{
    "prompt": "beautiful landscape",
    "negativePrompt": "people, buildings, cars"
  }],
  "parameters": {
    "aspectRatio": "16:9"
  }
}

种子值

通过 seed 参数实现可复现的生成结果：

{
  "instances": [{"prompt": "abstract art"}],
  "parameters": {
    "seed": 12345,
    "sampleCount": 1
  }
}

使用相同的 prompt 和 seed 可以生成相同的图片，适用于需要一致性的场景。

OpenAI 兼容方式（Imagen）

可以使用 OpenAI 风格的图像生成接口调用 Imagen：

curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-3.0-generate-001",
    "prompt": "a panda reading a book",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json"
  }'

Rivus AI 会自动完成参数映射：

size → aspectRatio（1024x1024 → 1:1，1792x1024 → 16:9，1024x1792 → 9:16）
n → sampleCount
response_format 支持 url 和 b64_json

常见参数

prompt：图像描述文本（必填）
negativePrompt：负面提示词（可选）
aspectRatio：宽高比（默认 1:1）
sampleCount：生成数量（默认 1）
seed：随机种子（可选）
personGeneration：人物生成控制（可选）

Rivus AI 会根据生成的图片数量自动计算用量和费用。Imagen 系列按每张 1290 image tokens 计费，你无需手动处理计费逻辑。

Gemini 图像模型：/v1/images/generations

Gemini 图像模型（如 gemini-2.5-flash-image-preview、gemini-3-pro-image-preview）结合了多模态推理与图像生成能力，推荐通过 OpenAI 兼容接口调用：

curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A futuristic cityscape at sunset with flying cars, cyberpunk style, highly detailed",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

使用 Python OpenAI SDK 调用

你也可以直接复用 Python openai 官方 SDK，通过配置 base_url 与 api_key 调用网关的 OpenAI 兼容接口：

from openai import OpenAI

client = OpenAI(
    base_url="https://models.rivus.cn/v1",
    api_key="oh-xxxxxxxxxxxxxxxx",
)

resp = client.images.generate(
    model="gemini-3-pro-image-preview",
    prompt="A futuristic cityscape at sunset with flying cars",
    size="1024x1024",
    response_format="b64_json",
)

image_b64 = resp.data[0].b64_json

支持的模型

gemini-2.5-flash-image-preview：快速生成，适合原型验证
gemini-3-pro-image-preview：高质量生成，适合生产环境

宽高比设置

支持通过 size 或 aspect_ratio 参数控制图像比例：

# 使用 size 参数
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "landscape photography of mountains",
    "size": "1792x1024"
  }'

# 使用 aspect_ratio 参数（优先级更高）
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "portrait of a scientist",
    "aspect_ratio": "9:16"
  }'

支持的宽高比：

1:1：正方形（默认）
16:9：横向宽屏
9:16：竖向

技术实现

Rivus AI 会将 OpenAI 风格请求转换为 Gemini 官方 generateContent 调用： 请求转换：

路径：/gemini/v1beta/models/{model}:generateContent
prompt → contents[].parts[].text
size / aspect_ratio → generationConfig.imageConfig.aspectRatio
固定参数：generationConfig.imageConfig.imageSize: "4K"（高保真）

响应处理：

优先提取 inlineData（官方标准格式）
兼容部分上游返回的 markdown data URL 格式（![image](data:image/png;base64,...)）

计费说明

Gemini 图像模型采用混合计费模式：

文本输入：按模型的文本 tokens 单价计费（从 UsageMetadata.promptTokenCount 获取）
图像输出：每张图片固定计为 1290 image tokens，对应官方 $0.134/张的定价

示例：

输入：50 tokens × $0.00001875/token = $0.0009375
输出：1 张图片 × 1290 tokens × $0.00010/token = $0.129
总计：$0.1299375

Rivus AI 会自动从 Gemini 响应的 UsageMetadata 中提取文本 tokens，并叠加图像 tokens（1290/张），确保计费准确。

与 Imagen 的对比

特性	Gemini 图像模型	Imagen 系列
推理能力	✅ 支持复杂提示词理解	❌ 纯文生图
图像质量	高保真（4K）	高质量
宽高比	1:1 / 16:9 / 9:16	1:1 / 16:9 / 9:16 / 4:3 / 3:4
批量生成	❌ 单张	✅ 最多 4 张
计费模式	文本 + 图像 tokens	仅图像 tokens
推荐场景	需要理解复杂语义	批量生成、简单提示词

对于需要 Gemini 推理能力的场景（如复杂提示词、上下文理解），优先使用 gemini-3-pro-image-preview；对于批量生成或简单文生图，使用 imagen-3.0-generate-001 更经济。

Authorizations

Authorization

string

header

required

OpenAI 风格认证（Authorization: Bearer ）

Body

application/json

model

enum<string>

required

模型名称

Available options:

imagen-3.0-generate-001,

gemini-2.5-flash-image-preview,

gemini-3-pro-image-preview

Example:

"gemini-3-pro-image-preview"

prompt

string

required

图像描述文本

Maximum string length: 4000

Example:

"A futuristic cityscape at sunset with flying cars, cyberpunk style, highly detailed"

integer

default:1

生成图片数量（Imagen 支持 1-4，Gemini 仅支持 1）

Required range: 1 <= x <= 4

size

enum<string>

default:1024x1024

图像尺寸

Available options:

1024x1024,

1792x1024,

1024x1792

Example:

"1024x1024"

aspect_ratio

enum<string>

宽高比（优先级高于 size）

Available options:

1:1,

16:9,

9:16

Example:

"1:1"

response_format

enum<string>

default:url

响应格式

Available options:

url,

b64_json

Response

200 - application/json

图像生成成功

created

integer

创建时间戳

data

object[]

Show child attributes

data.url

string

图片 URL（response_format=url 时）

data.b64_json

string

Base64 编码的图片（response_format=b64_json 时）

概述

核心功能

OpenAI 风格 API

Gemini 原生 API

其他

Imagen 系列：/gemini/v1beta/models/:predict

基础请求

响应示例

宽高比设置

批量生成

人物生成控制

负面提示词

种子值

OpenAI 兼容方式（Imagen）

常见参数

Gemini 图像模型：/v1/images/generations

使用 Python OpenAI SDK 调用

支持的模型

宽高比设置

技术实现

计费说明

与 Imagen 的对比

Authorizations

Body

Response

概述

核心功能

OpenAI 风格 API

Gemini 原生 API

其他

​Imagen 系列：/gemini/v1beta/models/:predict

​基础请求

​响应示例

​宽高比设置

​批量生成

​人物生成控制

​负面提示词

​种子值

​OpenAI 兼容方式（Imagen）

​常见参数

​Gemini 图像模型：/v1/images/generations

​使用 Python OpenAI SDK 调用

​支持的模型

​宽高比设置

​技术实现

​计费说明

​与 Imagen 的对比

Authorizations

Body

Response

Imagen 系列：/gemini/v1beta/models/:predict

基础请求

响应示例

宽高比设置

批量生成

人物生成控制

负面提示词

种子值

OpenAI 兼容方式（Imagen）

常见参数

Gemini 图像模型：/v1/images/generations

使用 Python OpenAI SDK 调用

支持的模型

宽高比设置

技术实现

计费说明

与 Imagen 的对比