Unode
使用指南接口文档帮助支持商务合作

Google Gemini 图像格式（Image）

Google Gemini 图像格式（Image）

官方文档

Google Gemini Generating content API

📝 简介

给定文本提示，模型将生成新的图片。Google Gemini 提供强大的图像生成模型，可以根据自然语言描述创建图像。

🤖 支持的模型

目前支持的模型包括：

模型描述
gemini-2.5-flash-imageGoogle Gemini 图像生成模型，支持根据文本提示生成高质量图像
gemini-3.1-flash-image-previewGoogle Gemini 快速图像生成模型（预览版）
gemini-3-pro-image-previewGoogle Gemini 图像生成和编辑模型，支持根据文本提示生成图像，以及基于输入图像和文本提示进行图像编辑
imagen-4.0-fast-generate-001Google Imagen 4.0 快速图像生成模型

💡 请求示例

创建图片 ✅

# 基础图片生成
curl "https://www.unodetech.xyz/v1beta/models/gemini-2.5-flash-image:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "给我一个猫的图片"}]
    }]
  }'

响应示例:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is an image for you: "
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "..."
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 1298,
    "totalTokenCount": 1307,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 9
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "IMAGE",
        "tokenCount": 1290
      }
    ]
  },
  "modelVersion": "gemini-2.5-flash-image",
  "responseId": "..."
}

使用 URL 交付生成图片

# 生成图片并返回临时 URL
curl "https://www.unodetech.xyz/v1beta/models/gemini-2.5-flash-image:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "给我一个猫的图片"}]
    }],
    "generationConfig": {
      "responseFormat": {
        "image": {"delivery": "URI"}
      }
    }
  }'

响应示例:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is an image for you: "
          },
          {
            "fileData": {
              "mimeType": "image/png",
              "fileUri": "https://cdn.example.com/generated-images/...?..."
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ]
}

编辑图片 ✅

# 图片编辑
curl "https://www.unodetech.xyz/v1beta/models/gemini-3-pro-image-preview:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "put the chips in the given image on a beach."},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "$IMG_BASE64"
          }
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "2K"
      }
    }
  }'

响应示例:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is the edited image for you: "
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "..."
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 15,
    "candidatesTokenCount": 1350,
    "totalTokenCount": 1365,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 15
      },
      {
        "modality": "IMAGE",
        "tokenCount": 1200
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "IMAGE",
        "tokenCount": 1350
      }
    ]
  },
  "modelVersion": "gemini-3-pro-image-preview",
  "responseId": "..."
}

📮 请求

端点

创建图片

POST /v1beta/models/gemini-2.5-flash-image:generateContent

根据文本提示创建图片。

编辑图片

POST /v1beta/models/gemini-3-pro-image-preview:generateContent

基于输入图像和文本提示编辑或生成新图片。支持 gemini-2.5-flash-image 和 gemini-3-pro-image-preview 模型。

鉴权方法

在请求URL参数中包含API密钥：

?key=$API_KEY

其中 $API_KEY 是您的 API 密钥。

请求体参数

contents

  • 类型：数组
  • 必需：是
  • 说明：包含生成请求的内容数组。

Content 对象属性：

属性类型必需描述
parts数组是有序的内容部分，构成单个消息

Part 对象属性：

属性类型必需描述
text字符串是（创建图片时）期望生成或编辑图片的文本描述
inline_data对象是（编辑图片时）输入图像数据（用于图片编辑）
text (在 parts 中)
  • 类型：字符串
  • 必需：是（创建图片时必需，编辑图片时也必需）
  • 说明：期望生成或编辑图片的文本描述。
  • 提示：
    • 使用具体和详细的描述
    • 包含关键的视觉元素
    • 指定期望的艺术风格
    • 描述构图和视角
    • 编辑图片时，描述希望如何修改输入图像
inline_data (在 parts 中，用于图片编辑)
  • 类型：对象
  • 必需：是（编辑图片时）
  • 说明：要编辑的输入图像数据。

InlineData 对象属性（请求中）：

属性类型必需描述
mime_type字符串是图像的MIME类型（如 "image/jpeg"、"image/png"）
data字符串是base64编码的图像数据

generationConfig (可选)

  • 类型：对象
  • 必需：否
  • 说明：用于控制生成行为的配置参数。

GenerationConfig 对象属性：

属性类型必需描述
responseModalities数组否指定响应中应包含的模态类型，如 ["TEXT", "IMAGE"]
imageConfig对象否图像生成配置参数
responseFormat对象否响应格式选项。将 image.delivery 设为 "URI" 可请求图片 URL。

ImageConfig 对象属性：

属性类型必需描述
aspectRatio字符串否图像的宽高比，如 "1:1"、"16:9" 等
imageSize字符串否图像尺寸，如 "2K"、"4K" 等

ResponseFormat Image 对象属性：

属性类型必需描述
delivery字符串否设为大写的 "URI"，可为每张生成的图片请求一个 URL。省略时保留上游响应格式。

📥 响应

成功响应

candidates

  • 类型：数组
  • 说明：模型的候选回答列表

Candidate 对象属性：

属性类型描述
content对象模型返回的生成内容
finishReason枚举模型停止生成的原因
index整数响应候选列表中候选项的索引

Content 对象属性：

属性类型描述
parts数组生成的内容部分，可能包含文本和图像
role字符串内容的生产者，通常为 "model"

Part 对象属性：

属性类型描述
text字符串文本内容；部分上游会在此处以 Markdown 数据 URL 的形式嵌入生成的图片
inlineData对象未请求 URL 交付或回退时返回的 Base64 图片数据
fileData对象URL 交付成功时返回的图片 URL，或上游原生图片 URI

InlineData 对象属性：

属性类型描述
mimeType字符串图像的MIME类型（如 "image/png"）
data字符串base64编码的图像数据

FileData 对象属性：

属性类型描述
mimeType字符串图片的 MIME 类型（例如 image/png）
fileUri字符串生成图片的 URL

FinishReason 枚举值：

  • STOP: 模型的自然停止点
  • MAX_TOKENS: 已达到请求中指定的词元数量上限
  • SAFETY: 出于安全考虑，系统已标记回答候选内容
  • IMAGE_SAFETY: 由于生成的图片违反了安全规定，因此词元生成已停止
  • OTHER: 原因未知

usageMetadata

  • 类型：对象
  • 说明：有关生成请求令牌用量的元数据

UsageMetadata 对象属性：

属性类型描述
promptTokenCount整数提示中的词元数
candidatesTokenCount整数所有生成的候选回答中的词元总数
totalTokenCount整数生成请求的总令牌数
promptTokensDetails数组在请求输入中处理的模态列表
candidatesTokensDetails数组响应中返回的模态列表

candidatesTokensDetails 对象属性：

属性类型描述
modality枚举与此令牌数关联的模态（TEXT、IMAGE等）
tokenCount整数令牌数量

modelVersion

  • 类型：字符串
  • 说明：用于生成回答的模型版本

responseId

  • 类型：字符串
  • 说明：用于标识每个响应的ID

promptFeedback (可选)

  • 类型：对象
  • 说明：与内容过滤器相关的提示反馈

图片对象示例

设置 "delivery": "URI" 时：

{
  "fileData": {
    "mimeType": "image/png",
    "fileUri": "https://cdn.example.com/generated-images/...?..."
  }
}

未请求 URL 交付时，图片可能以 Base64 形式返回：

{
  "inlineData": {
    "mimeType": "image/png",
    "data": "..."
  }
}

图片 URL 交付

URL 交付适用于非流式 generateContent 请求。根据模型的不同，图片数据可能位于 candidates.content.parts 中的 inlineData 对象，也可能直接作为 Markdown 出现在 text 对象中。

临时 URL 会过期。收到 URL 后请尽快下载或转存图片。

URL 交付错误

HTTP 状态码错误代码建议操作
400无效请求使用非流式 generateContent 请求及有效的 responseFormat JSON。只有大写的 "URI" 才会启用 URL 交付。
502image_url_delivery_failed严格模式下存储或 URL 签名失败；请稍后重试。
502image_response_too_large减少图片数量或尺寸。
503image_url_delivery_unavailable当前 API 密钥或流量暂时无法使用 URL 交付。
503其他 image_delivery_* 错误等待容量或运行状态恢复后，采用退避策略重试。

🌟 最佳实践

Prompt 编写建议

  1. 使用清晰具体的描述
  2. 指定重要的视觉细节
  3. 描述期望的艺术风格和氛围
  4. 注意构图和视角的说明
  5. 可以包含颜色、光线、情绪等细节

参数选择建议

  1. 模型选择

    • gemini-2.5-flash-image：适合快速生成高质量图像
    • gemini-3-pro-image-preview：支持图像生成和编辑，适合需要基于现有图像进行编辑的场景

  2. Prompt 优化

    • 使用详细和描述性的文本
    • 包含具体的视觉元素和风格要求
    • 避免模糊或过于简短的描述
    • 编辑图片时，明确描述希望如何修改输入图像（添加、移除、替换元素等）

  3. 安全设置

    • 根据应用场景调整安全阈值

常见问题

  1. 图片生成失败

    • 检查 prompt 是否符合内容政策
    • 验证 API 密钥权限
    • 确认请求格式正确

  2. 结果与预期不符

    • 优化 prompt 描述，使其更加具体和详细
    • 添加更多视觉细节和风格描述
    • 尝试不同的描述方式

  3. 安全过滤问题

    • 修改 prompt 以避免触发安全过滤器

最后更新于

目录

Google Gemini 图像格式（Image）
📝 简介
🤖 支持的模型
💡 请求示例
创建图片 ✅
使用 URL 交付生成图片
编辑图片 ✅
📮 请求
端点
创建图片
编辑图片
鉴权方法
请求体参数
contents
text (在 parts 中)
inline_data (在 parts 中，用于图片编辑)
generationConfig (可选)
📥 响应
成功响应
candidates
usageMetadata
modelVersion
responseId
promptFeedback (可选)
图片对象示例
图片 URL 交付
URL 交付错误
🌟 最佳实践
Prompt 编写建议
参数选择建议
常见问题