Generate Switch images with one of eight models: GPT Image 2.5, Switch Pro, Seedream 5.5, Switch Ultra, Nano Banana 2.1 (Google's newest, up to 14 reference pictures), Nano Banana 2, Nano Banana Pro or Switch Vintage. Nothing older is offered or accepted. When model is omitted it auto-routes by subject: GPT Image 2.5 by default and for typography, screens and storyboards, Switch Pro for swimwear/beach, Switch Ultra for sexier content or face-fidelity work. The Nano Bananas and Switch Vintage are only used when named. Switch Vintage is a film look that works from a character taught beforehand, not from reference pictures. Counts <= 8 render inline in chat; counts > 8 queue to your Switch Studio with progress polling. All images persist to your Studio library and folder. Optional `style` (e.g. "wellness/warm_amber_tropical", "movie_scene/neon_noir_action") applies a curated photographic stack from the apply_* skill tools.
View input schema
{
"type": "object",
"properties": {
"brand_kit": {
"type": "string",
"description": "Optional. Only for work made for a brand when the person wants their brand kit used: the kit by name or id, or \"settings\" for the kit chosen in Switch Agent settings. Leave out otherwise: no brand kit is sent."
},
"prompt": {
"type": "string",
"description": "The same as subject, for apps that call it prompt. Send one of subject or prompt."
},
"subject": {
"type": "string",
"description": "Plain-English description of what to generate. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony, model wearing a robe\". Name the creator's staged Studio references as @Image1, @Image2 (their image strip, see get_my_active_references) and they attach automatically; nothing from the strip attaches unless named."
},
"count": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"description": "How many images to generate. Default 4. <= 8 returns inline, > 8 queues to Studio. Beta limit: max 50 per request — larger asks are capped at 50 and the response says so."
},
"style": {
"type": "string",
"enum": [
"iphone_realism/digital_phone",
"iphone_realism/film_pointshoot",
"iphone_realism/off_duty_intimate",
"movie_scene/neon_noir_action",
"movie_scene/glamour_finance_excess",
"movie_scene/superhero_blockbuster",
"movie_scene/video_game_character",
"movie_scene/generic_action_thriller",
"high_fashion_editorial/glossy_cover",
"high_fashion_editorial/dark_cinematic",
"high_fashion_editorial/hard_flash_conceptual",
"high_fashion_editorial/painterly_renaissance",
"high_fashion_editorial/dreamlike_fairytale",
"high_fashion_editorial/black_and_white_natural",
"high_fashion_editorial/off_duty_candid",
"graphic_editorial_portrait/classic",
"graphic_editorial_portrait/golden_hour",
"travel/hotel_hero",
"travel/rural_property",
"travel/scenic_view",
"travel/drone_aerial",
"travel/lifestyle",
"travel/interior",
"wellness/warm_amber_tropical",
"wellness/hanalei_cinematic",
"wellness/high_key_cyan_beach",
"cinematic_anamorphic/warm_golden",
"cinematic_anamorphic/cool_noir",
"cinematic_anamorphic/moody_desaturated",
"magic_hour_portrait/canon_85mm",
"magic_hour_portrait/hasselblad_80mm",
"product/clean_studio",
"product/lifestyle",
"product/macro_detail",
"product/flat_lay",
"ugc/phone_shot",
"ugc/film_pointshoot",
"ugc/mirror_selfie",
"ugc/car_selfie"
],
"description": "Optional curated style stack from the apply_* skill tools. Format \"<skill>/<style_key>\", e.g. \"wellness/warm_amber_tropical\" or \"high_fashion_editorial/painterly_renaissance\"."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1",
"4:5",
"5:4",
"3:2",
"2:3",
"4:3",
"21:9",
"auto"
],
"description": "Image aspect ratio. auto (Nano Banana with a reference picture only): the new picture keeps the reference picture's own shape. Default 9:16 (vertical, social-friendly), or the shape a chosen style names. 21:9 is the wide cinema shape. Switch Vintage takes 9:16, 16:9, 4:3, 3:4, 1:1, 2:3 and 3:2 as is; any other ratio is mapped to the nearest one it offers."
},
"resolution": {
"type": "string",
"enum": [
"0.5K",
"1K",
"2K",
"4K"
],
"description": "Optional picture size, the same choices as the Studio size picker: 0.5K, 1K, 2K or 4K. Default 2K. Charged at the size picked. The picture shown in chat is a small preview; the saved one (images[].url) is full size."
},
"reference_roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"reference",
"face",
"body",
"product",
"clothes",
"location",
"style",
"typography"
]
},
"description": "Optional, one per reference_image_urls entry, in the same order: what that picture is for, as on the Studio strip (reference, face, body, product, clothes, location, style, typography). Left out = reference. face takes an asset id from upload_reference_asset (checked like face_reference_ids)."
},
"characters": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional. Names of the person's characters from the Models page. Their saved pictures go with the picture by role, like @Name in the Studio."
},
"camera_angles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional camera angle ids from the Studio angles panel, e.g. birds-eye, high-drone, low-drone, orbit-drone, reveal-drone, top-down-flat."
},
"enhance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional enhance ids from the Studio angles panel: lens-85mm, lens-50mm, lens-35mm, lens-24mm, lens-135mm, lens-200mm, lens-macro, lens-tilt, lens-fisheye, lens-vintage, dof-shallow, dof-medium, dof-deep, dof-bokeh-circles, dof-foreground, dof-subject-iso, dof-starburst, dof-tilt-plane, dof-pano-sharp, dof-creamy, grain-fine, grain-heavy, grain-portra, grain-tri-x, grain-cinestill, grain-fuji, grain-none, sharp-razor, sharp-soft, sharp-micro, sharp-crunchy, sharp-matte, sharp-glossy, sharp-clarity, sharp-dehaze, sharp-filmic, sharp-digital, cam-r5, cam-a7iv, cam-z8, cam-gfx, cam-hasselblad, cam-leica, cam-phase, cam-iphone, cam-polaroid, cam-disposable, light-softbox, light-ring, light-beauty-dish, light-umbrella, light-strip, light-barn-doors, light-gel-color, light-natural-ref, light-window-sheer, light-practical."
},
"skin": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional skin preset ids: iphone-quality, amateur-framing, film-grain, pores-skin, subsurface, skin-variation, discoloration, freckles, peach-fuzz, oily-sheen, under-eye, sun-damage, flush, acne-scars, moles, expression-lines, goosebumps, chapped-lips, stretch-marks."
},
"lighting": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional lighting preset ids: natural-window, golden-hour, morning, overcast, overhead-noon, shadow-mode, cinematic, twilight, candlelight, neon-night, studio-soft, rim-light, hard-flash, available-light, practical-light, diffused-indoor, bounce-fill."
},
"face_expression": {
"type": "boolean",
"description": "Optional. Keeps the same person and only varies the facial expression (the Studio face expression switch)."
},
"transparent_background": {
"type": "boolean",
"description": "Optional. See-through background. GPT Image models only, as in the Studio."
},
"real_photo_look": {
"type": "boolean",
"description": "Optional. Adds the casual real-photo texture (film grain, amateur iPhone feel). OFF by default — only set true when the user asks for the realistic, unpolished look."
},
"model": {
"type": "string",
"enum": [
"GPT Image 2.5",
"Switch Pro",
"Seedream 5.5",
"Switch Ultra",
"Nano Banana 2.1",
"Nano Banana 2",
"Nano Banana Pro",
"Switch Vintage"
],
"description": "Optional explicit model: GPT Image 2.5, Switch Pro, Seedream 5.5 (up to 10 reference pictures; 1 to 4 tokens a picture, more with more references), Switch Ultra, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro or Switch Vintage. Nothing else is accepted. Switch Vintage works from a character taught beforehand: pass no reference_image_urls or face_reference_ids with it. If omitted, auto-routed to GPT Image 2.5, Switch Pro or Switch Ultra by subject (see tool description)."
},
"reference_image_urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional GENERIC references (products, scenery, outfits, style). Each entry accepts EITHER a Switch asset id (from upload_reference_asset / upload_media / list_my_assets) OR a public https url; asset ids are resolved server-side. Pictures of real people go here too, as they are; you never pick a face field."
},
"face_reference_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional, kept for apps that already use it: asset ids from upload_reference_asset to use as the face to keep. Not needed to send a picture of a person; reference_image_urls takes those as they are. Each id is verified server-side (your own untouched original + identity verification) before anything generates or is charged."
},
"folder_name": {
"type": "string",
"description": "Optional Switch Studio folder name. Auto-created if missing. Defaults to the chat-derived title."
}
},
"required": []
}