Google Nano Banana 2.1 | Vtrix API Docs

API Notes

nano_banana_2_1 supports text-to-image generation, image editing, and multi-reference composition through the platform asynchronous generation API

nano_banana_2_1 returns generated image URLs in output[].content[]; generated text and thinking images are not delivered as separate outputs

nano_banana_2_1 accepts either prompt with optional image_urls, or native contents; when contents is supplied, outer prompt and image_urls are ignored, so place all text and reference images inside contents

nano_banana_2_1 does not support tools, toolConfig, cachedContent, previous_interaction_id, response_format, or generation_config; these fields cause the task to fail

nano_banana_2_1 uses a fixed response modality configuration; response_modalities cannot configure image-only or interleaved text output

Authentication

authorization `string` required

All APIs require authentication via Bearer Token.

Get API Key:

Visit API Key Management Page to get your API Key.

Usage:

Add to request header:

Authorization: Bearer YOUR_API_KEY

Parameters

Send requests to POST https://cloud.vtrix.ai/model/v1/generation. The examples on the right show text-to-image generation, image editing, and two reference images. Replace all example image URLs with publicly accessible image URLs

model `string` required

Public model identifier, placed at the top level of the request

Value: nano_banana_2_1

input `array` required

Generation input array. Put the following image generation parameters inside input[0].params

prompt `string`

Text instructions describing the image to generate or edit. Required when using the simplified request form without contents

Prompt guidelines:

Text-to-image: Specify the subject, scene, style, and lighting
Image editing: Describe what to change and what to preserve
Multiple references: Explain the role of each reference image and how to combine them

image_urls `array<string>`

Reference image URLs for image editing or multi-reference composition. Use URLs that the platform can download without additional authentication

aspect_ratio `string`

Output image aspect ratio. If omitted, the model determines the ratio

Examples: 1:1, 16:9

resolution `string`

Output image resolution

Options: 1K, 2K, 4K

Default: 1K

thinking_level `string`

Controls the model thinking level. Thinking content is not delivered as a separate output

Options: minimal, medium, high

Default: medium

Advanced Parameters

These parameters also belong inside input[0].params. When using native content entries, put all text and reference images inside contents

contents `array<object>`

Native content entries for advanced image requests. Each entry contains role and parts; text uses parts[].text, and reference images use parts[].inlineData.mimeType and parts[].inlineData.data. Image data must be Base64-encoded image bytes without a data URI prefix. Include the complete content history when providing multiple turns, and retain thoughtSignature values already available in that history

generationConfig `object`

Native nested generation settings, including imageConfig.aspectRatio, imageConfig.imageSize, and thinkingConfig.thinkingLevel. If the corresponding convenience fields aspect_ratio, resolution, or thinking_level are also supplied, they take precedence over these nested settings

systemInstruction `object`

System instructions provided as a parts array with text entries

safetySettings `array<object>`

Native safety settings containing category and threshold entries. Requests remain subject to model safety checks

Advanced Request Example

This request uses contents instead of outer prompt and image_urls. Replace BASE64_PRODUCT_IMAGE and BASE64_SCENE_IMAGE with the Base64 contents of your PNG reference images

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "model": "nano_banana_2_1",
  "input": [
    {
      "params": {
        "contents": [
          {
            "role": "user",
            "parts": [
              {
                "text": "Place the product from the first image in the scene from the second image"
              },
              {
                "inlineData": {
                  "mimeType": "image/png",
                  "data": "BASE64_PRODUCT_IMAGE"
                }
              },
              {
                "inlineData": {
                  "mimeType": "image/png",
                  "data": "BASE64_SCENE_IMAGE"
                }
              }
            ]
          }
        ],
        "systemInstruction": {
          "parts": [
            {
              "text": "Preserve the product shape and logo."
            }
          ]
        },
        "generationConfig": {
          "imageConfig": {
            "aspectRatio": "16:9",
            "imageSize": "2K"
          },
          "thinkingConfig": {
            "thinkingLevel": "high"
          }
        }
      }
    }
  ]
}'

Polling

Since result generation takes time, you need to poll the task status after creating the task.

The initial response only returns information such as the task ID and initial status. The final result must be obtained by polling the task status endpoint using the task ID.

See the examples on the right for polling requests and responses.

Query GET https://cloud.vtrix.ai/model/v1/generation/task/{task_id} using the id returned by creation. The status: "completed" in the creation receipt confirms acceptance only; it does not mean that the image is ready. The same task may subsequently be in_progress when queried

Continue querying while the task is processing. Read output only from a completed query response; stop polling on failed and inspect error. Reuse the same task ID when checking status instead of submitting another generation request

Query status	Action
`in_queue`	Wait and query again
`in_progress`	Wait and query again
`completed`	Read generated images from `output[].content[]`
`failed`	Stop polling and read `error.code` and `error.message`

Response Format

The right-side examples illustrate the creation receipt, a processing query response, and a successful query response. IDs, URLs, and usage values are illustrative; response examples show a subset of fields

Field	Type	Description
`id`	`string`	Task ID used for subsequent queries
`created_at`	`integer`	Creation timestamp in milliseconds
`status`	`string`	Task status; interpret creation receipts as described in Polling
`model`	`string`	Public model identifier
`request_id`	`string`	Request correlation ID, when present
`output`	`array`	Generated resources in successful query responses
`output[].content[].type`	`string`	`image`
`output[].content[].url`	`string`	Download URL for the generated image
`output[].content[].mime_type`	`string`	Actual image MIME type, such as `image/png` or `image/jpeg`
`error`	`object`	Failure details; may be `null` on a successful creation receipt
`error.code`	`string`	Error code
`error.message`	`string`	Error description
`usage`	`object`	Usage information, when available
`metadata`	`object`	Additional task timing information, when present

Token Usage

Gemini usage fields and usage.extra_info describe the measured usage. Do not assume generic prompt_tokens, completion_tokens, or total_tokens fields are populated. Optional usage fields may be omitted when their value is zero or no detail is available

Field under `usage`	Description
`promptTokenCount`	Total measured input tokens
`promptTokensDetails`	Input token details by modality; entries contain `modality` and `tokenCount`
`candidatesTokenCount`	Candidate output tokens, excluding separately reported thinking tokens
`candidatesTokensDetails`	Candidate token details by modality
`thoughtsTokenCount`	Separately reported thinking tokens
`totalTokenCount`	Total reported token usage
`extra_info.input_text_tokens`	Text input tokens, including unclassified input tokens
`extra_info.input_image_tokens`	Reference image input tokens
`extra_info.output_text_tokens`	Candidate text tokens, unclassified candidate tokens, and thinking tokens combined
`extra_info.output_image_tokens`	Generated image output tokens
`extra_info.thoughts_tokens`	Thinking token breakdown, already included in `output_text_tokens`
`extra_info.num_images`	Number of delivered final images
`cost`	Request cost in USD

These usage fields are read from the response and do not need to be supplied in the request

Error Codes

A task can be accepted and fail later during processing. The failure response uses string error codes; the message depends on the specific failure

{
  "id": "mmsu_example_task_id",
  "created_at": 1791763200000,
  "status": "failed",
  "model": "nano_banana_2_1",
  "error": {
    "code": "RUNTIME_CREATE_PREPARE_FAILED",
    "message": "Unsupported request field: tools"
  }
}

Error code	Description
`RUNTIME_CREATE_PREPARE_FAILED`	Request preparation failed, for example because an unsupported field was supplied
`RUNTIME_CREATE_PROVIDER_FAILED`	Model execution failed, for example because the requested resolution was invalid

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "nano_banana_2_1", "input": [ { "params": { "prompt": "A banana product photo on a white background", "aspect_ratio": "16:9", "resolution": "1K", "thinking_level": "medium" } } ] }'

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "nano_banana_2_1", "input": [ { "params": { "prompt": "Change the background to light blue and keep the product unchanged", "image_urls": [ "https://example.com/reference-image.png" ], "resolution": "1K", "thinking_level": "medium" } } ] }'

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "nano_banana_2_1", "input": [ { "params": { "prompt": "Place the product from the first image in the scene from the second image", "image_urls": [ "https://example.com/product.png", "https://example.com/scene.png" ], "aspect_ratio": "16:9", "resolution": "2K", "thinking_level": "high" } } ] }'

{ "id": "mmsu_example_task_id", "created_at": 1791763200000, "status": "completed", "model": "nano_banana_2_1", "output": [ { "content": [ { "mime_type": "image/png", "type": "image", "url": "https://example.com/generated-image.png" } ] } ], "usage": { "promptTokenCount": 8, "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 8 } ], "candidatesTokenCount": 1120, "candidatesTokensDetails": [ { "modality": "IMAGE", "tokenCount": 1120 } ], "thoughtsTokenCount": 608, "totalTokenCount": 1736, "cost": "0.038172", "extra_info": { "input_text_tokens": 8, "output_text_tokens": 608, "output_image_tokens": 1120, "thoughts_tokens": 608, "num_images": 1, "total_tokens": 1736 } }, "metadata": { "completed_at": 15.03, "in_queue_at": 0, "upload_at": 0 } }

API Notes

Authentication

authorization string required

Parameters

model string required

input array required

prompt string

image_urls array<string>

aspect_ratio string

resolution string

thinking_level string