Gemini image generation

Call Gemini image models via the official protocol. Text-to-image and image-to-image share the same endpoint; see Available models below for positioning and capability differences.

POST /v1beta/models/{model}:generateContent

Image-to-image does not need a different endpoint—append reference images as in .

Available models

Model	Positioning & capabilities	Output resolution	Reference images
	Flagship (Nano Banana Pro): professional asset production and complex multi-turn editing; strongest world knowledge and text rendering, finest composition and detail control; suited to posters, infographics, and accuracy-critical work	/ /	Official limit 14 images
	General workhorse (Nano Banana 2): balanced speed and quality; strong at multi-reference fusion and character consistency; only model in the family that supports extreme ratios , , ,	Supports / / / ; current channel is fixed around (ignores )	Official limit 14 images
	Previous generation (Nano Banana): speed and cost focused; suited to high-concurrency, low-latency bulk generation	Fixed (about )	Official recommendation: no more than 3

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer Token, for example:
	string	Yes	Request content type; must be

Request body

Name	Type	Required	Description
	array	Yes	Input content array; usually a single element
	object	No	Generation config, including output modalities and image settings
	array	No	Safety filter settings; optional

contents item

Name	Type	Required	Description
	string	No	Message role; fixed to
	array	Yes	Content parts array. Text-to-image uses only; for image-to-image, after append one per reference image (multiple supported)

parts.inlineData (reference image; image-to-image only)

Name	Type	Required	Description
	string	Yes	Reference image MIME type: , ,
	string	Yes	Base64-encoded reference image content

generationConfig.imageConfig

Name	Type	Required	Description
	array	Yes	Output modalities. Image generation must include ; recommended
	string	No	Output aspect ratio: , , , , , , , , , ; default . also supports extreme ratios , , ,
	string	No	Output resolution: , , ; default . Some models also support (0.5K, no K suffix). Note: Flash Image channels such as ignore this field and always return about 1K
	number	No	Sampling temperature, range to ; default
	number	No	Nucleus sampling parameter; default
	integer	No	Top-K sampling parameter
	integer	No	Maximum output tokens; for image generation, recommend at least
	integer	No	Random seed. The same seed improves reproducibility

Request example

Text-to-image

curl -X POST https://octopusx.ai/v1beta/models/gemini-3-pro-image-preview:generateContent \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [
      { "text": "Futuristic AI workstation scene with cinematic lighting" }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
  }
}'

Image-to-image

curl -X POST https://octopusx.ai/v1beta/models/gemini-3-pro-image-preview:generateContent \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [
      { "text": "Blend the reference styles and output a landscape poster" },
      { "inlineData": { "mimeType": "image/jpeg", "data": "BASE64_IMAGE_1" } },
      { "inlineData": { "mimeType": "image/jpeg", "data": "BASE64_IMAGE_2" } }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
  }
}'

Response example

200

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        { "inlineData": { "mimeType": "image/png", "data": "BASE64_OR_URL" } }
      ]
    },
    "finishReason": "STOP"
  }],
  "usageMetadata": {
    "promptTokenCount": 123,
    "candidatesTokenCount": 456,
    "totalTokenCount": 579
  },
  "modelVersion": "gemini-3-pro-image-preview"
}

Response fields

Name	Type	Description
	array	Candidate results array
	string	Finish reason. means normal completion; means blocked by safety policy
	object	Generated image content
	string	Image MIME type, usually
	string	Image data as Base64 or an image URL; clients should handle both
	integer	Input token count
	integer	Output token count
	integer	Total token count
	string	Actual model version used

Related endpoints

• Image APIs overview
• Error codes