概览
GoModel 暴露了用于图片生成和编辑的兼容 OpenAI 的图片端点。已经在调用 OpenAI/v1/images/generations 或 /v1/images/edits 的客户端和 SDK,无需修改即可指向 GoModel。
请求通过与聊天和嵌入相同的注册表按模型路由,因此 model 选择、provider 提示、虚拟模型、按密钥的模型访问规则(用户路径)、预算和速率限制全部适用。图片生成由 OpenAI 以及实现了该端点的兼容 OpenAI 提供商(Azure OpenAI、OpenRouter、xAI)提供,也由 Google Gemini 提供:Gemini 图片模型通过原生 API 提供,另有 Vertex AI 上的 Imagen。图片编辑由 OpenAI 和 Azure OpenAI、Gemini 图片模型(gemini-2.5-flash-image 等),以及任何在 /images/edits 上接受 OpenAI 多部分(multipart)上传的兼容 OpenAI 提供商提供。不具备该能力的提供商会返回明确的 model "…" does not support image generation(或 image edits)错误,而不会错误路由;对于不支持图片的提供商,仅支持图片的模型会从 /v1/models 中隐藏。
支持的端点
生成图片
model 和 prompt 为必填项。其他所有字段(n、size、quality、style、response_format、background、output_format、output_compression、moderation、user,以及未来的任何参数)都会原样转发给提供商,因此无需更新网关即可使用模型特有的选项。由提供商决定接受哪些值,否则返回其自身的错误。例外是 Gemini 的原生适配器,它会将 n 和 size 转换为对应的原生参数,请参阅 Google Gemini。
响应采用 OpenAI 图片响应封装。data[] 条目包含托管的 url(DALL·E,response_format: "url")或内联的 b64_json(gpt-image-1 始终返回 base64)。GoModel 会添加一个 provider 字段,标明处理该请求的提供商类型;其余内容都会原样透传,包括 usage 块以及 gpt-image-1 回显的输出参数。
编辑图片
编辑请求以multipart/form-data 上传源图片和可选的蒙版,与 OpenAI 端点的要求完全一致。image、prompt 和 model 为必填项;多张源图片以 image[] 发送(gpt-image-1 最多接受 16 张)。mask 是一张 PNG 图片,其透明像素标记需要修改的区域。
n、size、quality、response_format、background、output_format、input_fidelity、user 等)都会原样转发给提供商。上传的文件计入网关的请求体大小限制(BODY_SIZE_LIMIT)。
成本追踪
图片调用会记录在用量追踪中,端点为/v1/images/generations 和 /v1/images/edits:
当提供商报告输入 Token 时,提示词始终按 input_per_mtok 计价。生成的图片按以下两种方式之一计费,绝不会同时使用两种方式,具体由报告的用量决定:
- 按 Token 计费的模型(
gpt-image-1、Gemini 图片模型)会报告usage。GoModel 存储 Token 数量,并按模型的output_image_per_mtok费率(回退到output_per_mtok)为生成的 Token 计价。图片输出费率正是提供商在此收取的费率:gpt-image-1根本没有文本输出价格,而 Gemini 3 Pro Image 的图片输出按 $120/Mtok 计费,文本则为 $12/Mtok。这种计价方式对任何尺寸和质量都是精确的。 - 按图片计费的模型(DALL·E、
grok-imagine-image、Imagen)不报告 Token。GoModel 记录返回的图片数量(原始用量数据中的images),并按模型的per_image费率计价。
per_image 相当于一张典型图片 Token 费用的固定等价值(对于 1290 Token 的 gemini-2.5-flash-image,为 $0.039)。如果响应报告了生成的 Token,则仅按这些 Token 计价,因此两者永远不会叠加。
如果定价无法计算生成图片的成本(没有适用于响应所报告的图片输出 Token 的费率,或者既没有报告输出 Token、也没有 per_image/per_request 费率),该用量记录会被标记一条成本计算说明,显示为“未报告的用量”,而不是一次免费调用。
当模型目录中没有某个图片模型的价格时,可通过定价覆盖或在 config.yaml 中设置 per_image:
限制
图片端点是一个按模型路由、直通提供商的轻量通道,不会经过完整的推理编排器。与/v1/chat/completions 相比:
- 不支持故障转移、护栏或响应缓存:这些阶段会被跳过。请求仍会经过授权、预算检查、速率限制、计量,并写入审计日志。
- 不支持流式传输:
stream: true会被以400拒绝,因为流式图片生成以 Server-Sent Events 形式交付,而这些端点不会转发它们。省略stream(或将其设置为false)即可接收完整的 JSON 响应。 - 不暴露变体接口(
/v1/images/variations)。请使用透传 API(/p/{provider}/v1/images/...)在特定提供商上调用。 - 入站使用 OpenAI 请求格式:Google Gemini 的原生图片 API(Imagen
predict、Gemini 图片模型generateContent)会在这些端点背后进行转换;请参阅下文的提供商说明。其他原生图片 API 与 OpenAI 不同的提供商不会被转换,请对它们使用透传。
Google Gemini
当 Gemini 提供商处于原生 API 模式(默认)时,Gemini 图片模型(gemini-2.5-flash-image 等)通过 generateContent 生成图片,imagen-* 模型则通过 Imagen 的 predict API 生成。Google 已于 2026 年 8 月 17 日从 Gemini API(AI Studio)中下线 Imagen,请在该平台上使用 Gemini 图片模型;Imagen 仍可在 Vertex AI 上使用。
- Gemini 图片模型不支持多候选输出,因此
n(最大 10)会以n个并行的generateContent调用来处理,并合并其结果;每次调用都会由 Google 单独计费。对于 Imagen,n映射为sampleCount;size映射为最接近的受支持宽高比(1024x1024→1:1、1536x1024→3:2等),而"16:9"这样的原始比例会直接透传。未知的 JSON 字段会原样转发,因此原生参数(personGeneration、sampleImageSize、imageConfig等)可直接使用。 - 图片始终以
b64_json返回。Gemini 图片模型随图片一起生成的任何文本都会以revised_prompt返回。 - Gemini 图片模型会报告 Token
usage(按 Token 计费);Imagen 不报告(请按per_image计价)。 - 编辑仅适用于 Gemini 图片模型:上传的内容会作为内联图片部分放在提示词之前。不支持
mask,请在提示词中描述需要修改的区域。Imagen 模型仅支持生成。
/openai/images/generations 端点,编辑请求会被拒绝(该接口没有编辑端点)。
审计日志
图片请求与其他模型交互一样会出现在审计日志中。启用LOGGING_LOG_BODIES 时:
- 生成请求以 JSON 形式存储。编辑请求以图片体形式存储:包含提示词和参数,以及每张上传的源图片和蒙版各一项(文件名、内容类型、大小)。
- 响应同样以图片体形式存储:包含响应封装(
created、usage、size、quality等),以及每张返回的图片各一项。托管 URL 以链接形式保留。
LOGGING_LOG_IMAGE_BODIES=true,否则不会存储像素本身。开启后,上传的图片和生成的图片会写入媒体存储,每一项都带有一个 media_id,控制台通过 GET /admin/media/{id} 内联显示;LOGGING_LOG_IMAGE_BODIES_SCOPE 可将范围限制为 input(编辑上传)或 output(结果)。未开启时,每张图片都是一个带大小信息的占位符(stored: false)。无论哪种方式,条目都会保持精简且完整:即使是很大的 b64_json 结果,也绝不会触发通用的 1 MB 请求体截断,且对每条记录中存储的图片没有数量上限。文件的保留时间与引用它们的审计条目相同(LOGGING_RETENTION_DAYS)。