{
  "openapi": "3.1.0",
  "info": {
    "title": "Nano Banana Image API",
    "version": "1.0.0",
    "description": "Gemini-native synchronous and asynchronous image generation with the current YingTu Nano Banana model family."
  },
  "servers": [
    {
      "url": "https://api.yingtu.ai",
      "description": "YingTu API"
    }
  ],
  "tags": [
    {
      "name": "Synchronous generation",
      "description": "Wait for a complete Gemini response in one HTTP request."
    },
    {
      "name": "Asynchronous tasks",
      "description": "Submit image work, then retrieve the task until it reaches a terminal state."
    }
  ],
  "paths": {
    "/v1beta/models/{model}:generateContent": {
      "post": {
        "tags": ["Synchronous generation"],
        "summary": "Generate an image synchronously (billable)",
        "description": "This sends a real, billable image request. Check the current model price at https://api.yingtu.ai/pricing before sending. The operation runs a Gemini-native generation or editing request and returns the complete response on the same connection.",
        "operationId": "generateImageSynchronously",
        "security": [
          {"BearerAuth": []}
        ],
        "parameters": [
          {"$ref": "#/components/parameters/Model"}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/GenerateContentRequest"},
              "examples": {
                "textToImage": {
                  "summary": "Generate a landscape image",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {"text": "A quiet reading room at sunrise, editorial photography"}
                        ]
                      }
                    ],
                    "generationConfig": {
                      "responseModalities": ["TEXT", "IMAGE"],
                      "imageConfig": {
                        "aspectRatio": "16:9"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Complete Gemini response",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/GenerateContentResponse"},
                "examples": {
                  "verifiedImageResult": {
                    "summary": "Representative completed image response",
                    "value": {
                      "candidates": [
                        {
                          "content": {
                            "role": "model",
                            "parts": [
                              {
                                "inlineData": {
                                  "mimeType": "image/jpeg",
                                  "data": "BASE64_IMAGE_DATA"
                                }
                              }
                            ]
                          },
                          "finishReason": "STOP",
                          "index": 0
                        }
                      ],
                      "usageMetadata": {
                        "promptTokenCount": 37,
                        "candidatesTokenCount": 1846,
                        "totalTokenCount": 1883,
                        "promptTokensDetails": [
                          {"modality": "TEXT", "tokenCount": 37}
                        ],
                        "candidatesTokensDetails": [
                          {"modality": "IMAGE", "tokenCount": 1680}
                        ]
                      },
                      "modelVersion": "gemini-3.1-flash-image",
                      "responseId": "response_example"
                    }
                  }
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"},
          "413": {"$ref": "#/components/responses/RequestTooLarge"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/ServerError"}
        }
      }
    },
    "/v1beta/models/{model}:asyncGenerateContent": {
      "post": {
        "tags": ["Asynchronous tasks"],
        "summary": "Submit an asynchronous image task (billable)",
        "description": "This sends a real, billable image request. Check the current model price at https://api.yingtu.ai/pricing before sending. The operation accepts the same Gemini-native body as the synchronous method, persists a YingTu task, and returns HTTP 202 without waiting for image generation to finish.",
        "operationId": "submitAsynchronousImageTask",
        "security": [
          {"BearerAuth": []}
        ],
        "parameters": [
          {"$ref": "#/components/parameters/Model"}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/GenerateContentRequest"},
              "examples": {
                "textToImage": {
                  "summary": "Queue a landscape image",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {"text": "A quiet reading room at sunrise, editorial photography"}
                        ]
                      }
                    ],
                    "generationConfig": {
                      "responseModalities": ["TEXT", "IMAGE"],
                      "imageConfig": {
                        "aspectRatio": "16:9"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Task accepted",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/TaskAccepted"},
                "example": {
                  "task_id": "task_example",
                  "status": "queued",
                  "created_at": 1788311383
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"},
          "413": {"$ref": "#/components/responses/RequestTooLarge"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/ServerError"}
        }
      }
    },
    "/v1/tasks/{task_id}": {
      "get": {
        "tags": ["Asynchronous tasks"],
        "summary": "Get an asynchronous image task",
        "description": "Returns the current state and, after completion, the Gemini-native result for a task created by the authenticated YingTu account.",
        "operationId": "getAsynchronousImageTask",
        "security": [
          {"BearerAuth": []}
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "description": "Task ID returned by asyncGenerateContent.",
            "schema": {"type": "string"},
            "example": "task_01JY8K6M6B4YQ3R8H4T6V2Z1AB"
          }
        ],
        "responses": {
          "200": {
            "description": "Current task state",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Task"},
                "examples": {
                  "completed": {
                    "summary": "Completed image task",
                    "value": {
                      "task_id": "task_example",
                      "status": "completed",
                      "progress": "100%",
                      "model": "gemini-3.1-flash-image",
                      "created_at": 1788311383,
                      "started_at": 1788311384,
                      "completed_at": 1788311393,
                      "result": {
                        "candidates": [
                          {
                            "content": {
                              "role": "model",
                              "parts": [
                                {
                                  "inlineData": {
                                    "mimeType": "image/jpeg",
                                    "data": "BASE64_IMAGE_DATA"
                                  }
                                }
                              ]
                            },
                            "finishReason": "STOP",
                            "index": 0
                          }
                        ],
                        "usageMetadata": {
                          "promptTokenCount": 37,
                          "candidatesTokenCount": 1533,
                          "totalTokenCount": 1570
                        },
                        "modelVersion": "gemini-3.1-flash-image",
                        "responseId": "response_example"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "404": {
            "description": "Task not found for this account",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/ErrorResponse"}
              }
            }
          },
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/ServerError"}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "YingTu API key."
      }
    },
    "parameters": {
      "Model": {
        "name": "model",
        "in": "path",
        "required": true,
        "description": "Current Nano Banana model ID.",
        "schema": {"$ref": "#/components/schemas/ModelId"},
        "example": "gemini-3.1-flash-image"
      }
    },
    "schemas": {
      "ModelId": {
        "type": "string",
        "enum": [
          "gemini-2.5-flash-image",
          "gemini-3.1-flash-lite-image",
          "gemini-3.1-flash-image",
          "gemini-3-pro-image"
        ]
      },
      "GenerateContentRequest": {
        "type": "object",
        "required": ["contents"],
        "properties": {
          "contents": {
            "title": "Prompt and input",
            "type": "array",
            "minItems": 1,
            "items": {"$ref": "#/components/schemas/RequestContent"},
            "description": "Messages sent to the model."
          },
          "tools": {
            "type": "array",
            "items": {"type": "object", "additionalProperties": true},
            "description": "Optional Gemini tools. Availability depends on the selected image model."
          },
          "toolConfig": {
            "type": "object",
            "additionalProperties": true,
            "description": "Configuration for tools declared in tools."
          },
          "safetySettings": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/SafetySetting"}
          },
          "systemInstruction": {"$ref": "#/components/schemas/RequestContent"},
          "cachedContent": {
            "type": "string",
            "description": "Optional cached content resource name when supported by the selected model."
          },
          "generationConfig": {
            "title": "Output settings",
            "$ref": "#/components/schemas/GenerationConfig"
          }
        }
      },
      "RequestContent": {
        "type": "object",
        "required": ["parts"],
        "properties": {
          "role": {
            "title": "Role",
            "type": "string",
            "enum": ["user", "model"],
            "default": "user",
            "description": "Message sender. Use user for a new request."
          },
          "parts": {
            "title": "Prompt or media",
            "type": "array",
            "minItems": 1,
            "items": {"$ref": "#/components/schemas/RequestPart"},
            "description": "Prompt text and optional source media."
          }
        }
      },
      "ResponseContent": {
        "type": "object",
        "required": ["parts"],
        "properties": {
          "role": {
            "type": "string",
            "const": "model"
          },
          "parts": {
            "type": "array",
            "minItems": 1,
            "items": {"$ref": "#/components/schemas/ResponsePart"}
          }
        }
      },
      "RequestPart": {
        "description": "Choose one Part type.",
        "oneOf": [
          {"$ref": "#/components/schemas/TextPart"},
          {"$ref": "#/components/schemas/InlineDataPart"},
          {"$ref": "#/components/schemas/FileDataPart"},
          {"$ref": "#/components/schemas/FunctionCallPart"},
          {"$ref": "#/components/schemas/FunctionResponsePart"},
          {"$ref": "#/components/schemas/ExecutableCodePart"},
          {"$ref": "#/components/schemas/CodeExecutionResultPart"}
        ]
      },
      "TextPart": {
        "title": "Text prompt",
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": {"type": "string", "description": "Prompt or edit instruction."}
        }
      },
      "InlineDataPart": {
        "title": "Source image",
        "type": "object",
        "required": ["inlineData"],
        "properties": {
          "inlineData": {"$ref": "#/components/schemas/InlineData"}
        }
      },
      "FileDataPart": {
        "title": "File URI part",
        "type": "object",
        "required": ["fileData"],
        "properties": {
          "fileData": {"$ref": "#/components/schemas/FileData"}
        }
      },
      "FunctionCallPart": {
        "title": "Function call part",
        "type": "object",
        "required": ["functionCall"],
        "properties": {
          "functionCall": {"$ref": "#/components/schemas/FunctionCall"}
        }
      },
      "FunctionResponsePart": {
        "title": "Function response part",
        "type": "object",
        "required": ["functionResponse"],
        "properties": {
          "functionResponse": {"$ref": "#/components/schemas/FunctionResponse"}
        }
      },
      "ExecutableCodePart": {
        "title": "Executable code part",
        "type": "object",
        "required": ["executableCode"],
        "properties": {
          "executableCode": {"$ref": "#/components/schemas/ExecutableCode"}
        }
      },
      "CodeExecutionResultPart": {
        "title": "Code execution result part",
        "type": "object",
        "required": ["codeExecutionResult"],
        "properties": {
          "codeExecutionResult": {"$ref": "#/components/schemas/CodeExecutionResult"}
        }
      },
      "ResponsePart": {
        "description": "Choose exactly one response data type. Metadata may accompany that data.",
        "oneOf": [
          {"$ref": "#/components/schemas/ResponseTextPart"},
          {"$ref": "#/components/schemas/ResponseInlineDataPart"},
          {"$ref": "#/components/schemas/ResponseFileDataPart"},
          {"$ref": "#/components/schemas/ResponseFunctionCallPart"},
          {"$ref": "#/components/schemas/ResponseFunctionResponsePart"},
          {"$ref": "#/components/schemas/ResponseExecutableCodePart"},
          {"$ref": "#/components/schemas/ResponseCodeExecutionResultPart"}
        ]
      },
      "ResponsePartMetadata": {
        "type": "object",
        "properties": {
          "thought": {"type": "boolean"},
          "thoughtSignature": {"type": "string", "format": "byte"},
          "partMetadata": {"type": "object", "additionalProperties": true},
          "mediaResolution": {"type": "object", "additionalProperties": true},
          "videoMetadata": {"type": "object", "additionalProperties": true}
        }
      },
      "ResponseTextPart": {
        "allOf": [
          {"$ref": "#/components/schemas/ResponsePartMetadata"},
          {"$ref": "#/components/schemas/TextPart"}
        ]
      },
      "ResponseInlineDataPart": {
        "allOf": [
          {"$ref": "#/components/schemas/ResponsePartMetadata"},
          {"$ref": "#/components/schemas/InlineDataPart"}
        ]
      },
      "ResponseFileDataPart": {
        "allOf": [
          {"$ref": "#/components/schemas/ResponsePartMetadata"},
          {"$ref": "#/components/schemas/FileDataPart"}
        ]
      },
      "ResponseFunctionCallPart": {
        "allOf": [
          {"$ref": "#/components/schemas/ResponsePartMetadata"},
          {"$ref": "#/components/schemas/FunctionCallPart"}
        ]
      },
      "ResponseFunctionResponsePart": {
        "allOf": [
          {"$ref": "#/components/schemas/ResponsePartMetadata"},
          {"$ref": "#/components/schemas/FunctionResponsePart"}
        ]
      },
      "ResponseExecutableCodePart": {
        "allOf": [
          {"$ref": "#/components/schemas/ResponsePartMetadata"},
          {"$ref": "#/components/schemas/ExecutableCodePart"}
        ]
      },
      "ResponseCodeExecutionResultPart": {
        "allOf": [
          {"$ref": "#/components/schemas/ResponsePartMetadata"},
          {"$ref": "#/components/schemas/CodeExecutionResultPart"}
        ]
      },
      "InlineData": {
        "title": "Inline image",
        "type": "object",
        "required": ["mimeType", "data"],
        "properties": {
          "mimeType": {
            "title": "Image MIME type",
            "type": "string",
            "enum": ["image/png", "image/jpeg", "image/webp"],
            "example": "image/png"
          },
          "data": {
            "title": "Image Base64",
            "type": "string",
            "description": "Raw Base64 without a data URL prefix.",
            "example": "BASE64_IMAGE_DATA"
          }
        }
      },
      "FileData": {
        "type": "object",
        "required": ["fileUri"],
        "properties": {
          "mimeType": {"type": "string", "description": "Optional IANA MIME type."},
          "fileUri": {"type": "string", "description": "URI of a Gemini File API resource."}
        }
      },
      "FunctionCall": {
        "type": "object",
        "required": ["name", "args"],
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "args": {"type": "object", "additionalProperties": true}
        }
      },
      "FunctionResponse": {
        "type": "object",
        "required": ["name", "response"],
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "response": {"type": "object", "additionalProperties": true}
        }
      },
      "ExecutableCode": {
        "type": "object",
        "required": ["language", "code"],
        "properties": {
          "language": {"type": "string"},
          "code": {"type": "string"}
        }
      },
      "CodeExecutionResult": {
        "type": "object",
        "required": ["outcome", "output"],
        "properties": {
          "outcome": {"type": "string"},
          "output": {"type": "string"}
        }
      },
      "SafetySetting": {
        "type": "object",
        "required": ["category", "threshold"],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "HARM_CATEGORY_HATE_SPEECH",
              "HARM_CATEGORY_SEXUALLY_EXPLICIT",
              "HARM_CATEGORY_DANGEROUS_CONTENT",
              "HARM_CATEGORY_HARASSMENT",
              "HARM_CATEGORY_CIVIC_INTEGRITY",
              "HARM_CATEGORY_JAILBREAK"
            ]
          },
          "threshold": {
            "type": "string",
            "enum": ["HARM_BLOCK_THRESHOLD_UNSPECIFIED", "BLOCK_LOW_AND_ABOVE", "BLOCK_MEDIUM_AND_ABOVE", "BLOCK_ONLY_HIGH", "BLOCK_NONE", "OFF"]
          }
        }
      },
      "GenerationConfig": {
        "type": "object",
        "properties": {
          "stopSequences": {
            "type": "array",
            "maxItems": 5,
            "items": {"type": "string"}
          },
          "responseMimeType": {"type": "string"},
          "responseSchema": {"type": "object", "additionalProperties": true},
          "responseJsonSchema": {"type": "object", "additionalProperties": true},
          "responseModalities": {
            "title": "Response type",
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": ["TEXT", "IMAGE"]
            },
            "example": ["TEXT", "IMAGE"],
            "description": "Include IMAGE to receive an image."
          },
          "candidateCount": {
            "title": "Number of outputs",
            "type": "integer",
            "enum": [1],
            "description": "Use one output."
          },
          "maxOutputTokens": {"type": "integer", "minimum": 1},
          "temperature": {"type": "number"},
          "topP": {"type": "number"},
          "topK": {"type": "number"},
          "seed": {"type": "integer", "format": "int64"},
          "presencePenalty": {"type": "number"},
          "frequencyPenalty": {"type": "number"},
          "responseLogprobs": {"type": "boolean"},
          "logprobs": {"type": "integer"},
          "enableEnhancedCivicAnswers": {"type": "boolean"},
          "mediaResolution": {"type": "string"},
          "thinkingConfig": {"$ref": "#/components/schemas/ThinkingConfig"},
          "speechConfig": {"type": "object", "additionalProperties": true},
          "imageConfig": {"$ref": "#/components/schemas/ImageConfig"}
        }
      },
      "ThinkingConfig": {
        "type": "object",
        "properties": {
          "includeThoughts": {"type": "boolean"},
          "thinkingBudget": {"type": "integer"},
          "thinkingLevel": {"type": "string", "enum": ["minimal", "high"]}
        },
        "description": "Thinking options when supported by the selected image model."
      },
      "ImageConfig": {
        "title": "Image settings",
        "type": "object",
        "properties": {
          "aspectRatio": {
            "title": "Aspect ratio",
            "type": "string",
            "enum": ["1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", "21:9"],
            "example": "1:1",
            "description": "Family-wide union. Check the selected model's Parameters page for its supported subset."
          },
          "imageSize": {
            "title": "Image size",
            "type": "string",
            "enum": ["1K", "2K", "4K"],
            "description": "Model-specific and case-sensitive. Omit for Gemini 2.5 Flash Image. Lite accepts an omitted value or 1K. Flash and Pro use 1K when omitted and accept 1K, 2K, or 4K."
          }
        }
      },
      "GenerateContentResponse": {
        "type": "object",
        "required": ["candidates"],
        "properties": {
          "candidates": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/Candidate"}
          },
          "promptFeedback": {"$ref": "#/components/schemas/PromptFeedback"},
          "usageMetadata": {"$ref": "#/components/schemas/UsageMetadata"},
          "modelVersion": {
            "type": "string",
            "description": "The model version that produced the response.",
            "example": "gemini-3.1-flash-image"
          },
          "responseId": {
            "type": "string",
            "description": "Provider response identifier.",
            "example": "response_example"
          },
          "createTime": {
            "type": "string",
            "format": "date-time",
            "description": "Creation time when supplied by the selected model channel."
          }
        }
      },
      "Candidate": {
        "type": "object",
        "required": ["content"],
        "properties": {
          "content": {"$ref": "#/components/schemas/ResponseContent"},
          "finishReason": {
            "type": "string",
            "example": "STOP"
          },
          "safetyRatings": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/SafetyRating"}
          },
          "groundingMetadata": {"$ref": "#/components/schemas/GroundingMetadata"},
          "index": {
            "type": "integer",
            "minimum": 0,
            "example": 0
          }
        }
      },
      "PromptFeedback": {
        "type": "object",
        "properties": {
          "blockReason": {"type": "string", "description": "Reason the prompt was blocked when no candidates are returned."},
          "safetyRatings": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/SafetyRating"}
          }
        }
      },
      "SafetyRating": {
        "type": "object",
        "properties": {
          "category": {"type": "string"},
          "probability": {"type": "string"}
        }
      },
      "GroundingMetadata": {
        "type": "object",
        "properties": {
          "webSearchQueries": {"type": "array", "items": {"type": "string"}}
        },
        "description": "Grounding metadata when preserved by the selected model and route."
      },
      "UsageMetadata": {
        "type": "object",
        "properties": {
          "promptTokenCount": {"type": "integer", "minimum": 0},
          "candidatesTokenCount": {"type": "integer", "minimum": 0},
          "totalTokenCount": {"type": "integer", "minimum": 0},
          "thoughtsTokenCount": {"type": "integer", "minimum": 0},
          "promptTokensDetails": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/ModalityTokenCount"}
          },
          "candidatesTokensDetails": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/ModalityTokenCount"}
          },
          "serviceTier": {"type": "string"},
          "trafficType": {"type": "string"}
        }
      },
      "ModalityTokenCount": {
        "type": "object",
        "required": ["modality", "tokenCount"],
        "properties": {
          "modality": {
            "type": "string",
            "example": "IMAGE"
          },
          "tokenCount": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "TaskAccepted": {
        "type": "object",
        "required": ["task_id", "status", "created_at"],
        "properties": {
          "task_id": {
            "type": "string",
            "example": "task_01JY8K6M6B4YQ3R8H4T6V2Z1AB"
          },
          "status": {
            "type": "string",
            "const": "queued"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in seconds.",
            "example": 1788307200
          }
        }
      },
      "Task": {
        "type": "object",
        "required": ["task_id", "model", "status", "progress", "created_at"],
        "properties": {
          "task_id": {"type": "string"},
          "model": {"$ref": "#/components/schemas/ModelId"},
          "status": {
            "type": "string",
            "enum": ["queued", "in_progress", "completed", "failed"]
          },
          "progress": {
            "type": "string",
            "example": "100%"
          },
          "created_at": {"type": "integer", "format": "int64"},
          "started_at": {"type": "integer", "format": "int64"},
          "completed_at": {"type": "integer", "format": "int64"},
          "result": {"$ref": "#/components/schemas/GenerateContentResponse"},
          "error": {"$ref": "#/components/schemas/TaskError"}
        }
      },
      "TaskError": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "message": {
            "type": "string",
            "example": "Gemini upstream returned no image data"
          }
        }
      },
      "ErrorObject": {
        "type": "object",
        "required": ["message", "type"],
        "properties": {
          "message": {"type": "string"},
          "type": {"type": "string", "example": "invalid_request_error"},
          "param": {"type": ["string", "null"]},
          "code": {"type": ["string", "null"], "example": "insufficient_user_quota"}
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {"$ref": "#/components/schemas/ErrorObject"}
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid model, field, or parameter value",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/ErrorResponse"}
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid YingTu API key",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/ErrorResponse"}
          }
        }
      },
      "Forbidden": {
        "description": "The key is valid but the account lacks balance or access for this request",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/ErrorResponse"},
            "example": {
              "error": {
                "message": "Insufficient balance for this request",
                "type": "new_api_error",
                "param": "",
                "code": "insufficient_user_quota"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "The official upstream provider returned a rate, quota, spend, or model-capacity limit. The documented Nano Banana gateway routes do not apply a fixed platform-side RPM cap.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying when supplied.",
            "schema": {"type": "integer"}
          }
        },
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/ErrorResponse"}
          }
        }
      },
      "RequestTooLarge": {
        "description": "The decompressed request body exceeds a current ingress limit. Reduce the source image and total JSON body; the public contract does not promise one fixed source-image byte or pixel maximum.",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/ErrorResponse"},
            "example": {
              "error": {
                "message": "Request body exceeds the current limit",
                "type": "new_api_error",
                "param": "",
                "code": "read_request_body_failed"
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "The request could not be completed",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/ErrorResponse"}
          }
        }
      }
    }
  }
}