{
  "source": "https://ai.google.dev/gemini-api/docs/imagen",
  "retrieved": "2026-05-13",
  "sdk_package": "google-genai",
  "sdk_import": "from google import genai\nfrom google.genai import types",

  "models": [
    {
      "id": "imagen-4.0-generate-001",
      "label": "Imagen 4 Standard",
      "use_case": "Production — best balance of quality and speed",
      "supports_image_size": true
    },
    {
      "id": "imagen-4.0-ultra-generate-001",
      "label": "Imagen 4 Ultra",
      "use_case": "Highest quality output, slower — hero images and print",
      "supports_image_size": true
    },
    {
      "id": "imagen-4.0-fast-generate-001",
      "label": "Imagen 4 Fast",
      "use_case": "Drafts and rapid iteration — low latency",
      "supports_image_size": false
    }
  ],

  "deprecated_models": [
    { "id": "imagen-3.0-generate-001", "status": "discontinued" }
  ],

  "method": "client.models.generate_images",
  "rest_endpoint": "https://generativelanguage.googleapis.com/v1beta/models/{model}:predict",
  "auth_header": "x-goog-api-key",

  "parameters": {
    "model": {
      "type": "string",
      "required": true,
      "values": ["imagen-4.0-generate-001", "imagen-4.0-ultra-generate-001", "imagen-4.0-fast-generate-001"]
    },
    "prompt": {
      "type": "string",
      "required": true,
      "language": "English only",
      "max_tokens": 480,
      "notes": "Text overlays in images: keep under 25 characters for best results. Exact font replication not guaranteed."
    },
    "config": {
      "class": "types.GenerateImagesConfig",
      "fields": {
        "number_of_images": {
          "type": "integer",
          "min": 1,
          "max": 4,
          "default": 4
        },
        "aspect_ratio": {
          "type": "string",
          "default": "1:1",
          "values": ["1:1", "3:4", "4:3", "9:16", "16:9"],
          "notes": "Do NOT use '3:2' — not supported and will error"
        },
        "image_size": {
          "type": "string",
          "default": "1K",
          "values": ["1K", "2K"],
          "applies_to": ["imagen-4.0-generate-001", "imagen-4.0-ultra-generate-001"],
          "not_available_for": ["imagen-4.0-fast-generate-001"]
        },
        "person_generation": {
          "type": "string",
          "default": "allow_adult",
          "values": [
            { "value": "dont_allow", "description": "No people or faces in output — use for hardware, product, landscape" },
            { "value": "allow_adult", "description": "Adults only" },
            { "value": "allow_all", "description": "Adults and children — restricted in EU, UK, CH, MENA regions" }
          ]
        }
      }
    }
  },

  "output": {
    "watermark": "SynthID — embedded in all generated images, not visible",
    "format": "PIL Image object (SDK) / base64 bytes (REST)",
    "access_sdk": "response.generated_images[i].image"
  },

  "python_minimal_example": "from google import genai\nfrom google.genai import types\n\nclient = genai.Client()\nresponse = client.models.generate_images(\n    model='imagen-4.0-generate-001',\n    prompt='Your prompt here',\n    config=types.GenerateImagesConfig(\n        number_of_images=4,\n        aspect_ratio='16:9',\n        person_generation='dont_allow'\n    )\n)\nfor img in response.generated_images:\n    img.image.show()",

  "rest_minimal_example": "curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/imagen-4.0-generate-001:predict' -H 'x-goog-api-key: $GEMINI_API_KEY' -H 'Content-Type: application/json' -d '{\"instances\":[{\"prompt\":\"Your prompt\"}],\"parameters\":{\"sampleCount\":4}}'",

  "arising_media_defaults": {
    "draft_model": "imagen-4.0-fast-generate-001",
    "production_model": "imagen-4.0-generate-001",
    "hero_model": "imagen-4.0-ultra-generate-001",
    "person_generation": "dont_allow",
    "number_of_images": 4,
    "aspect_ratio_web_hero": "16:9",
    "aspect_ratio_square": "1:1",
    "aspect_ratio_portrait": "3:4",
    "file_naming": "{page}-{slot}.jpg",
    "workflow": "draft with fast → select variant → regenerate with standard or ultra"
  },

  "prompt_engineering_notes": [
    "Describe subject, environment, lighting, and mood in one sentence",
    "Photorealistic hardware/landscape: add 'photorealistic, 4K, professional photography'",
    "Avoid people/faces: include 'no people, no humans' explicitly when using dont_allow is not enough",
    "Camera style modifiers: 'shot on Canon 5D', 'wide angle lens', 'golden hour lighting'",
    "Art style: 'architectural render', 'flat illustration', 'watercolor wash'",
    "Keep text overlays short: 25 chars max, specify position ('top left', 'centered')"
  ],

  "known_errors": [
    {
      "error": "aspect ratio X:X not supported",
      "cause": "3:2 or other non-standard ratio passed",
      "fix": "Use only: 1:1, 3:4, 4:3, 9:16, 16:9"
    },
    {
      "error": "imageSize not applicable",
      "cause": "imageSize passed to imagen-4.0-fast-generate-001",
      "fix": "Remove imageSize parameter when using fast model"
    }
  ]
}