Generate Content (图像)
最近更新：2026年9月2日
用 Gemini generateContent 协议出图，与对话调用同一条地址，官方 SDK 直接可用。
图像模型走的是与对话调用完全相同的地址：POST /v1beta/models/{model}:generateContent。
出不出图由请求体里的 generationConfig.responseModalities 决定，没有单独的图像端点。
鉴权与路径规则沿用对话那一条：
x-goog-api-key: <你的 Amux 密钥> 或 URL 上的 ?key=，模型名里的斜杠不要转义。
https://gateway.amux.ai/v1beta/models/{model}:generateContent鉴权
headerAuthorizationstring必填控制台创建的 Amux 密钥。这是 Gemini SDK 原生发送的鉴权头。
Content-Typestring必填默认 "application/json"固定为 application/json。
请求
application/jsonmodelstring必填规范 ID，写在路径里。厂商/模型 中的斜杠不要转义。
contentsarray<object>必填提示词与参考图。文本放在 parts[].text，参考图放在 parts[].inline_data（base64 原始字节，不含 data: 前缀）。 出图与图生图走同一条端点，区别只在有没有参考图。
›contentsarray<object>
role"user" | "model"说话方。user 是你，model 是模型此前的回复。单轮请求可以省略。
partsarray<object>这一轮的片段，按给出的顺序生效。文本与参考图可以混在同一轮里。
›partsarray<object>
textstring文本片段。同一轮里多个 text 会按顺序拼接。
inline_dataobject内联的参考图。只接受内联字节与 Files API，不接受 URL。
›inline_dataobject
mime_typestring图片的媒体类型，如 image/png、image/jpeg、image/webp。
datastringbase64 原始字节，不含 data: 前缀。
generationConfigobject必填生成参数。出图相关的两项是 responseModalities 与 responseFormat.image。
›generationConfigobject
responseModalitiesarray<"TEXT" | "IMAGE">必填必填 ["TEXT", "IMAGE"]。缺了它，同一条端点只回文本。
responseFormatobject产物格式。图像相关的在 image 下。
›responseFormatobject
imageobject出图的尺寸控制。两项都可以省略，省略时由上游取默认。
›imageobject
aspectRatiostring画面比例。取值范围逐模型不同，见各模型页； 超出该模型支持范围的取值会被丢弃并在 amux.notes 中说明。
imageSize"512" | "1K" | "2K" | "4K"分辨率档位。取值范围逐模型不同，见各模型页。
toolsarray<object>联网检索。取值 [{ "google_search": {} }]。并非所有图像模型都支持， 不支持的模型会由上游拒绝。按检索次数计费，次数见响应的 groundingMetadata.webSearchQueries。
响应
200response生成结果。
出图的开关
responseModalities 必须写成 ["TEXT", "IMAGE"]。缺了它，同一条端点只返回文本——
这是最常见的一种「调通了但没有图」。
产物尺寸由 generationConfig.responseFormat.image 控制，两个字段：
aspectRatio—— 画面比例imageSize—— 分辨率档位，512/1K/2K/4K（最小那档不带px，官方原话是「必须用大写的 K」，而 512 这一档没有 K 后缀）
两者的取值范围逐模型不同，各模型支持哪些见「图像」一节下对应的模型页，例如 gemini-3-pro-image。
这条端点原样转发请求体——填了某个模型不接受的取值，由上游判定，通常直接返回 400。
经 OpenAI 兼容的图像端点或
Amux Tasks 调用时请求体由我们渲染，
那两条路径上超范围的取值会被丢弃并记入 amux.notes，上游随即使用它自己的默认值。
参考图
图生图与文生图共用这一条端点，区别只在 contents[].parts 里有没有 inline_data：
{
"parts": [
{ "text": "把这只猫换成橘色" },
{ "inline_data": { "mime_type": "image/jpeg", "data": "<base64>" } }
]
}data 是不含 data: 前缀的原始 base64。参考图张数上限逐模型不同。
以 URL 形式提供参考图不受支持：官方只接受内联字节与 Files API，
传 URL 会被丢弃并记入 amux.notes。
响应形状
图与文本在 candidates[].content.parts 里交错出现——图在 inlineData，
模型的说明文字在 text。要拿全部产物需要遍历整个 parts，只读第一项会漏。
usageMetadata 里，图像 token 与文本 token 在 candidatesTokensDetails 中按模态分开。
两者单价相差可达一个数量级，站内账单据此分项计费，不会把图像 token 按文本价计。
不支持的能力
- 流式。Gemini 的流式是换动作（
:streamGenerateContent），而官方文档 未给出图像流式的语法。因此图像模型上的流式请求会被拒绝，请去掉流式后重试。 - 一次多张。请求体中没有批量字段，一次调用返回一张图。
联网检索
tools: [{ "google_search": {} }] 可让模型在出图前检索。并非所有图像模型都支持，
不支持的模型由上游直接拒绝。
计费按检索次数：一次调用中模型可能发起多条查询，实际条数见响应的
candidates[].groundingMetadata.webSearchQueries。
其他调用方式
同一批模型也可以通过 OpenAI 兼容的图像端点
与 Amux Tasks 调用。那两条路径经过协议转换，
本协议独有的参数会按参数支持矩阵取交集，
被丢弃的项同样记入 amux.notes。
错误
错误按 Gemini 的错误体形状返回，status 取值与重试语义见错误与重试。
curl https://gateway.amux.ai/v1beta/models/google/gemini-3-pro-image:generateContent \
-H "x-goog-api-key: $AMUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "<string>",
"inline_data": {
"mime_type": "image/png",
"data": "<string>"
}
}
]
}
],
"generationConfig": {
"responseModalities": [
"TEXT",
"IMAGE"
],
"responseFormat": {
"image": {
"aspectRatio": "16:9",
"imageSize": "2K"
}
}
},
"tools": [
{}
]
}'{
"candidates": [
{
"content": {
"parts": [
{
"text": "<string>",
"inlineData": {
"mimeType": "image/png",
"data": "<string>"
}
}
]
},
"groundingMetadata": {
"webSearchQueries": [
"<string>"
]
}
}
],
"usageMetadata": {
"promptTokenCount": 0,
"candidatesTokenCount": 0,
"totalTokenCount": 0,
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 0
}
],
"candidatesTokensDetails": [
{
"modality": "IMAGE",
"tokenCount": 0
}
]
}
}