{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/octen-ai/json-schema/octen-ai-image-generation-request-schema.json",
  "title": "ImageGenerationRequest",
  "description": "JSON request body for the Image Generation API.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/octen-ai-images-api-openapi.yml#/components/schemas/ImageGenerationRequest",
  "allOf": [
    {
      "$ref": "#/$defs/ImageGenerationBaseRequest"
    },
    {
      "type": "object",
      "properties": {
        "image": {
          "description": "Reference/source image(s) for editing, a data URL prefix or a raw base64 string. Providing an image enters edit mode. An array passes multiple reference images.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ]
        },
        "mask": {
          "type": "string",
          "description": "(GPT only) Mask image, base64-encoded PNG matching the input size. Transparent areas are repainted. Effective only when `image` is provided."
        }
      }
    }
  ],
  "$defs": {
    "ImageGenerationBaseRequest": {
      "type": "object",
      "required": [
        "model",
        "prompt"
      ],
      "description": "Shared parameters for the Image Generation API. Text-to-image when no image is provided; image editing when an image is provided. Parameters marked (GPT only) or (Gemini only) apply only to those model families; unsupported parameters are ignored.",
      "properties": {
        "model": {
          "type": "string",
          "enum": [
            "openai/gpt-image-2.5-flare",
            "openai/gpt-image-2.5-sunburst",
            "openai/gpt-image-2",
            "openai/gpt-image-1-mini",
            "google/gemini-3-pro-image",
            "google/gemini-3.1-flash-image"
          ],
          "description": "The model to use. Aliases `nano-banana-pro` (= `google/gemini-3-pro-image`) and `nano-banana-2` (= `google/gemini-3.1-flash-image`) are also accepted."
        },
        "prompt": {
          "type": "string",
          "description": "The text description for the model. The length limit is set by the model."
        },
        "n": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "default": 1,
          "description": "(GPT only) Number of images to generate. For Gemini, request multiple images in the `prompt` instead."
        },
        "size": {
          "type": "string",
          "default": "auto",
          "description": "Output size as `width x height` (e.g. `1024x1024`) or `auto`."
        },
        "quality": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "xhigh",
            "max",
            "auto"
          ],
          "default": "auto",
          "description": "(GPT only) Generation quality."
        },
        "background": {
          "type": "string",
          "enum": [
            "transparent",
            "opaque",
            "auto"
          ],
          "default": "auto",
          "description": "(GPT only) Background setting."
        },
        "output_format": {
          "type": "string",
          "enum": [
            "png",
            "jpeg",
            "webp"
          ],
          "default": "png",
          "description": "Output image format. GPT supports png/jpeg/webp; Gemini supports png/jpeg (webp falls back to png)."
        },
        "output_compression": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "default": 100,
          "description": "(GPT only) Compression level (percent). Effective only when `output_format` is jpeg or webp."
        },
        "moderation": {
          "type": "string",
          "enum": [
            "low",
            "auto"
          ],
          "default": "auto",
          "description": "(GPT only) Content moderation strength."
        },
        "thinking_level": {
          "type": "string",
          "enum": [
            "minimal",
            "high"
          ],
          "default": "minimal",
          "description": "(Gemini only) Thinking effort before generation."
        },
        "response_modalities": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "text",
              "image"
            ]
          },
          "default": [
            "text",
            "image"
          ],
          "description": "(Gemini only) Controls returned modalities. `[\"text\",\"image\"]` returns the image plus accompanying text; `[\"image\"]` returns only the image."
        },
        "media_resolution": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ],
          "description": "(Gemini only) Processing resolution for input reference images."
        },
        "response_format": {
          "type": "string",
          "enum": [
            "b64_json"
          ],
          "default": "b64_json",
          "description": "Return format."
        },
        "stream": {
          "type": "boolean",
          "default": false,
          "description": "(GPT only) Whether to stream the response."
        },
        "partial_images": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3,
          "default": 0,
          "description": "(GPT only) Number of intermediate preview images to stream. Effective only when `stream=true`. Each preview costs an extra 100 image output tokens."
        },
        "user": {
          "type": "string",
          "description": "A unique identifier for the end user. Use hashed or pseudonymous identifiers to avoid passing personally identifiable information."
        }
      }
    }
  }
}