{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hop-base.com/spec/models/gemini-3.1-flash-image.json",
  "title": "POST /v1/images/generations · gemini-3.1-flash-image",
  "description": "Gemini 3.1 Flash Image 的请求体契约，由插件校验代码导出的 spec 生成。未列出的字段网关会忽略或原样转发。",
  "type": "object",
  "required": [
    "model",
    "prompt"
  ],
  "properties": {
    "model": {
      "const": "gemini-3.1-flash-image"
    },
    "prompt": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "去除首尾空白后不能为空，否则 400「prompt must not be empty」"
    },
    "n": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 1,
      "description": "按输出档位封顶：1K ≤ 10，2K ≤ 5"
    },
    "image_size": {
      "enum": [
        "1K",
        "2K"
      ],
      "default": "1K"
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "2:3",
        "3:2",
        "3:4",
        "4:3",
        "4:5",
        "5:4",
        "9:16",
        "16:9",
        "21:9"
      ],
      "default": "1:1"
    },
    "size": {
      "description": "auto、任意比例的 宽x高（映射到最接近的官方比例，档位按长边推导并静默降到型号最高档位），或型号档位",
      "anyOf": [
        {
          "const": "auto"
        },
        {
          "type": "string",
          "pattern": "^[1-9][0-9]*x[1-9][0-9]*$"
        },
        {
          "enum": [
            "1K",
            "2K"
          ]
        }
      ]
    },
    "google": {
      "type": "object",
      "properties": {
        "image_config": {
          "type": "object",
          "properties": {
            "aspect_ratio": {
              "enum": [
                "1:1",
                "2:3",
                "3:2",
                "3:4",
                "4:3",
                "4:5",
                "5:4",
                "9:16",
                "16:9",
                "21:9"
              ]
            },
            "image_size": {
              "enum": [
                "1K",
                "2K"
              ]
            }
          }
        }
      }
    },
    "image": {
      "description": "参考图：字符串或字符串数组，最多 14 张",
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(https?://|data:image/)",
          "description": "HTTP(S) URL 或图片 Data URL"
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^(https?://|data:image/)",
            "description": "HTTP(S) URL 或图片 Data URL"
          },
          "minItems": 1,
          "maxItems": 14
        }
      ]
    },
    "images": {
      "description": "参考图：字符串或字符串数组，最多 14 张",
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(https?://|data:image/)",
          "description": "HTTP(S) URL 或图片 Data URL"
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^(https?://|data:image/)",
            "description": "HTTP(S) URL 或图片 Data URL"
          },
          "minItems": 1,
          "maxItems": 14
        }
      ],
      "$comment": "与 image 同时传时以 images 为准"
    },
    "mask": false,
    "background": {
      "not": {
        "const": "transparent"
      }
    },
    "stream": {
      "not": {
        "const": true
      }
    }
  },
  "allOf": [
    {
      "$comment": "2K 输出每次最多 5 张（响应体积上限）",
      "if": {
        "properties": {
          "image_size": {
            "const": "2K"
          }
        },
        "required": [
          "image_size"
        ]
      },
      "then": {
        "properties": {
          "n": {
            "type": "integer",
            "maximum": 5
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "size": {
            "const": "2K"
          }
        },
        "required": [
          "size"
        ]
      },
      "then": {
        "properties": {
          "n": {
            "type": "integer",
            "maximum": 5
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "google": {
            "type": "object",
            "properties": {
              "image_config": {
                "type": "object",
                "properties": {
                  "image_size": {
                    "const": "2K"
                  }
                },
                "required": [
                  "image_size"
                ]
              }
            },
            "required": [
              "image_config"
            ]
          }
        },
        "required": [
          "google"
        ]
      },
      "then": {
        "properties": {
          "n": {
            "type": "integer",
            "maximum": 5
          }
        }
      }
    }
  ],
  "additionalProperties": true,
  "x-hopbase": {
    "model_name": "Gemini 3.1 Flash Image",
    "family": "gemini-image",
    "endpoints": [
      "POST /v1/images/generations",
      "POST /v1/images/edits"
    ],
    "response_field": "data[].b64_json",
    "groups": [
      {
        "id": 18,
        "name": "Gemini 全系（含生图）",
        "name_en": "Gemini (all models, incl. image)",
        "note": "generations 参考图最多 14 张（网关校验）、远程 URL 单张 ≤ 25 MiB；另有 /v1/images/edits；按交付张数计费"
      },
      {
        "id": 23,
        "name": "Gemini 官方直连",
        "name_en": "Gemini Official Direct",
        "note": "参考图单张解码后 ≤ 20 MiB；没有 /v1/images/edits；按 token 计费、按实际生成档位计"
      }
    ],
    "pricing": {
      "currency": "USD",
      "label": "官方价，实际按分组倍率计费",
      "source": "https://api.hop-base.com/api/v1/models/pricing",
      "snapshot": "2026-09-25",
      "unit": "image",
      "per_image_by_tier": {
        "1K": 0.0672,
        "2K": 0.0672
      }
    },
    "rejected": [
      {
        "field": "mask",
        "status": 400,
        "message": "mask is not supported for Gemini image models; remove mask and describe the region to edit in the prompt"
      },
      {
        "field": "background",
        "value": "transparent",
        "status": 400,
        "message": "background=transparent is not supported for model gemini-3.1-flash-image; Gemini image models cannot output transparent images"
      },
      {
        "field": "stream",
        "value": true,
        "status": 400,
        "message": "Gemini image generation does not support stream=true; send a non-streaming request"
      }
    ],
    "references": {
      "max": 14,
      "enforced_by": "gateway",
      "max_bytes": 20971520
    },
    "tiers": [
      "1K",
      "2K"
    ],
    "tier_max_n": {
      "1K": 10,
      "2K": 5
    },
    "ignored": [
      "quality",
      "response_format",
      "output_format"
    ],
    "verified": {
      "date": null,
      "feed": "https://hop-base.com/docs-verified.json",
      "route": "media/images"
    },
    "docs": "https://hop-base.com/zh-cn/docs/media/images#gemini-banana-请求参数",
    "source": [
      "toc-landing/docs-app/spec/openai.json#images.gemini (airgate-openai)",
      "toc-landing/docs-app/spec/gemini.json#images (airgate-gemini)",
      "toc-landing/docs-app/spec/official.json#gemini (https://ai.google.dev/gemini-api/docs/image-generation)"
    ],
    "generated_by": "toc-landing/docs-app/scripts/build-model-schemas.mjs"
  }
}