参数、尺寸与错误
公共参数
| 参数 | 支持范围 |
|---|---|
n / output.count | 省略或 1 |
quality / output.quality | 省略或 auto |
output_format / output.format | 省略或 png |
response_format | 同步支持 url 或 b64_json；异步始终为 URL |
aspect_ratio / output.aspect_ratio | 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 |
resolution / output.resolution | 512、0.5K、1K、2K、4K；0.5K 会规范化为 512 |
mask / input.mask | 不支持 |
明确提交 background、output_compression、input_fidelity、style、moderation、partial_images、stream、watermark 或旧 extra_fields 会被拒绝。
| 模型 | 支持的 resolution |
|---|---|
gemini-3.1-flash-image | 512 / 0.5K / 1K / 2K / 4K |
gemini-3-pro-image-count | 1K / 2K / 4K |
未提交尺寸控制时默认使用 1:1/1K，避免静默提高生成成本。
标准尺寸映射
size | Gemini aspectRatio | Gemini imageSize |
|---|---|---|
1024x1024 | 1:1 | 1K |
1024x1536 | 2:3 | 1K |
1536x1024 | 3:2 | 1K |
2048x2048 | 1:1 | 2K |
2048x3072 | 2:3 | 2K |
3072x2048 | 3:2 | 2K |
其他标准尺寸会返回 unsupported_image_size。size 是兼容映射，不是精确像素承诺；例如 2048x3072 会请求 2:3/2K，部分 Adobe/We-AI 渠道可能实际返回 1696x2528。实际宽高始终以响应或资源元数据为准。
冲突按字段判断：
size不能与公开aspect_ratio、resolution或任何 providerimageConfig同时使用。aspect_ratio只与 providerimageConfig.aspectRatio冲突。resolution只与 providerimageConfig.imageSize冲突。- 公开字段可以与不控制同一字段的 provider 配置合并，例如公开
aspect_ratio与 providerimageSize。
provider_options.google
aspect_ratio 和 resolution 已是公开参数。provider_options.google 用于采样、thinking、安全策略等 Gemini 高级参数；旧 imageConfig 继续兼容 Adobe/We-AI 渠道。JSON 请求使用对象，multipart 请求使用 JSON 字符串：
{
"provider_options": {
"google": {
"generationConfig": {
"temperature": 0.8,
"topP": 0.95,
"topK": 40,
"seed": 7,
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "2K"
},
"thinkingConfig": {
"thinkingBudget": 256,
"thinkingLevel": "HIGH",
"includeThoughts": true
}
},
"safetySettings": [
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"threshold": "BLOCK_ONLY_HIGH"
}
]
}
}
}以下 snake_case 别名同样被接受，并在服务端统一为官方 camelCase：
| camelCase | snake_case |
|---|---|
generationConfig | generation_config |
safetySettings | safety_settings |
topP | top_p |
topK | top_k |
imageConfig | image_config |
aspectRatio | aspect_ratio |
imageSize | image_size |
thinkingConfig | thinking_config |
thinkingBudget | thinking_budget |
thinkingLevel | thinking_level |
includeThoughts | include_thoughts |
同一字段同时提交 camelCase 与 snake_case 会返回 duplicate_parameter。
禁止覆盖
provider_options 不能覆盖：
model、contents、endpoint 或鉴权；tools、systemInstruction；responseModalities、candidateCount。
这些字段由统一任务协议和服务端凭证租约控制。
Usage
{
"prompt_tokens": 25,
"completion_tokens": 1680,
"total_tokens": 1705,
"input_tokens": 25,
"output_tokens": 1680,
"cached_tokens": 0,
"image_tokens": 0,
"audio_tokens": 0,
"prompt_tokens_details": {
"image_tokens": 0,
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0
}
}输入图片 Token 只计入输入明细；输出图片和思考 Token 计入 completion。同步响应、异步查询、消费日志和 Webhook 使用同一份归一化 usage。
错误码
| 错误码 | 原因 |
|---|---|
unsupported_image_count | 请求输出数量不是 1 |
unsupported_mask | Gemini 编辑提交了 Mask |
unsupported_quality | quality 不是 auto |
unsupported_output_format | 输出格式不是 PNG |
unsupported_image_size | size 不在严格映射表内 |
unsupported_aspect_ratio | aspect_ratio 不在支持列表 |
unsupported_image_resolution | resolution 不受支持，或当前模型不支持该档位 |
duplicate_parameter | 别名重复，或多个字段控制同一比例/分辨率 |
invalid_provider_options | 命名空间、字段或值不在白名单 |
executor_not_configured | Gemini Images 执行器尚未配置 |
upstream_error | Gemini 上游请求失败 |
missing_image_result | 上游响应中没有图片 |
unexpected_image_count | 上游意外返回多张图片 |
"524" | 内部图片服务暂时不可用，可以有限重试 |
"524" 是统一图片任务协议的字符串业务错误码，不是 HTTP 524。任务查询仍返回任务对象，并以 status: "failed" 表示终态；公开响应和 Webhook 不会包含内部渠道、子分组、余额、供应商错误码或上游 Request ID。
仅当 error.retryable 为 true 时建议自动重试。终态失败后应使用新的 Idempotency-Key 创建新任务；复用原 Key 只会返回原失败任务。