Google Nano Banana 2.1 | Vtrix API Docs

接口提示

nano_banana_2_1 通过平台异步生成接口支持文生图, 图片编辑和多参考图组合

nano_banana_2_1 在 output[].content[] 中返回生成图片的 URL, 生成文本和思考图片不会作为独立结果交付

nano_banana_2_1 接受 prompt 搭配可选的 image_urls, 或原生 contents 两种请求形态；传入 contents 时会忽略外层 prompt 和 image_urls, 请将全部文本和参考图放入 contents

nano_banana_2_1 不支持 tools、toolConfig、cachedContent、previous_interaction_id、response_format 或 generation_config, 传入这些字段会导致任务失败

nano_banana_2_1 使用固定的响应模态配置, 不能通过 response_modalities 配置仅图片或图文交错输出

认证

authorization `string` 必填

所有 API 均使用 Bearer Token 鉴权

获取 API Key：

访问 API Key 管理页面获取 API Key

用法：

将以下 Header 添加到请求中：

Authorization: Bearer YOUR_API_KEY

参数

请求地址为 POST https://cloud.vtrix.ai/model/v1/generation. 右侧示例覆盖文生图, 图片编辑和双参考图. 请将示例图片 URL 替换为可公开访问的图片地址

model `string` 必填

公开模型标识, 放在请求体顶层

值：nano_banana_2_1

input `array` 必填

生成输入数组, 以下图像生成参数均放在 input[0].params 中

prompt `string`

用于描述生成或编辑图像的文本指令, 使用不含 contents 的简化请求形态时必填

提示词建议：

文生图：说明主体, 场景, 风格和光照
图片编辑：明确需要修改及保留的内容
多参考图：说明每张参考图的用途和组合方式

image_urls `array<string>`

用于图片编辑或多参考图组合的图片 URL 列表, 图片地址应允许平台无需额外认证即可下载

aspect_ratio `string`

输出图像的宽高比, 未传入时由模型决定

示例值：1:1, 16:9

resolution `string`

输出图像的分辨率

可选值：1K, 2K, 4K

默认值：1K

thinking_level `string`

控制模型思考等级, 思考内容不会作为独立结果交付

可选值：minimal, medium, high

默认值：medium

高级参数

以下参数同样放在 input[0].params 中. 使用原生内容结构时, 将文本和参考图完整放入 contents

contents `array<object>`

用于高级图像请求的原生内容条目, 每个条目包含 role 和 parts；文本使用 parts[].text, 参考图使用 parts[].inlineData.mimeType 和 parts[].inlineData.data. 图片数据应为图片字节的 Base64 编码, 不包含 data URI 前缀. 提供多轮内容时应携带完整历史, 并保留历史中已有的 thoughtSignature

generationConfig `object`

原生嵌套生成配置, 包括 imageConfig.aspectRatio、imageConfig.imageSize 和 thinkingConfig.thinkingLevel. 同时传入对应的便捷参数 aspect_ratio、resolution 或 thinking_level 时, 便捷参数优先于这些嵌套配置

systemInstruction `object`

系统指令, 通过包含文本条目的 parts 数组提供

safetySettings `array<object>`

包含 category 和 threshold 的原生安全设置, 请求仍需通过模型安全检查

高级请求示例

此请求使用 contents, 不传入外层 prompt 和 image_urls. 请将 BASE64_PRODUCT_IMAGE 和 BASE64_SCENE_IMAGE 替换为 PNG 参考图内容的 Base64 编码

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"
          }
        }
      }
    }
  ]
}'

轮询

由于结果生成需要时间，您需要在创建任务后轮询任务状态

初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取

轮询请求与响应示例见右侧

使用创建响应的 id 查询 GET https://cloud.vtrix.ai/model/v1/generation/task/{task_id}. 创建回执中的 status: "completed" 仅表示请求已受理, 不代表图片已经生成；随后查询同一任务时仍可能返回 in_progress

任务处理中应继续查询, 仅从已完成的查询响应读取 output；出现 failed 时停止轮询并检查 error. 查询状态时复用同一任务 ID, 不要重新提交生成请求

查询状态	处理方式
`in_queue`	等待后继续查询
`in_progress`	等待后继续查询
`completed`	从 `output[].content[]` 读取生成图片
`failed`	停止轮询, 读取 `error.code` 和 `error.message`

响应格式

右侧示例分别展示创建回执, 处理中查询响应和成功查询响应. ID、URL 和用量均为示例值, 响应示例仅展示部分字段

字段	类型	描述
`id`	`string`	用于后续查询的任务 ID
`created_at`	`integer`	毫秒级创建时间戳
`status`	`string`	任务状态, 创建回执的解释见轮询章节
`model`	`string`	公开模型标识
`request_id`	`string`	请求关联 ID, 存在时返回
`output`	`array`	成功查询响应中的生成资源
`output[].content[].type`	`string`	`image`
`output[].content[].url`	`string`	生成图片的下载地址
`output[].content[].mime_type`	`string`	图片实际 MIME 类型, 例如 `image/png` 或 `image/jpeg`
`error`	`object`	失败信息, 成功创建回执中可能为 `null`
`error.code`	`string`	错误码
`error.message`	`string`	错误描述
`usage`	`object`	可用时返回的用量信息
`metadata`	`object`	存在时返回的任务耗时信息

Token 用量

Gemini 用量字段和 usage.extra_info 描述实际计量结果. 不要依赖通用的 prompt_tokens、completion_tokens 或 total_tokens 字段始终有值. 可选用量字段在值为零或缺少明细时可能省略

`usage` 下的字段	描述
`promptTokenCount`	实际输入 token 总量
`promptTokensDetails`	按模态区分的输入 token 明细, 每项包含 `modality` 和 `tokenCount`
`candidatesTokenCount`	候选输出 token, 不包含单独报告的思考 token
`candidatesTokensDetails`	按模态区分的候选 token 明细
`thoughtsTokenCount`	单独报告的思考 token
`totalTokenCount`	报告的 token 总量
`extra_info.input_text_tokens`	文本输入 token, 包括未分类的输入 token
`extra_info.input_image_tokens`	参考图输入 token
`extra_info.output_text_tokens`	候选文本, 未分类候选及思考 token 的合计
`extra_info.output_image_tokens`	生成图片的输出 token
`extra_info.thoughts_tokens`	思考 token 明细, 已包含在 `output_text_tokens` 中
`extra_info.num_images`	交付的最终图片数量
`cost`	请求费用, 单位为 USD

以上用量字段仅用于读取响应, 无需在请求中传入

错误码

任务受理后仍可能在处理阶段失败. 失败响应使用字符串错误码, 错误消息以具体失败原因为准

{
  "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"
  }
}

错误码	描述
`RUNTIME_CREATE_PREPARE_FAILED`	请求准备失败, 例如传入不支持的字段
`RUNTIME_CREATE_PROVIDER_FAILED`	模型执行失败, 例如请求的分辨率无效

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 } }

接口提示

认证

authorization string 必填

参数

model string 必填

input array 必填

prompt string

image_urls array<string>

aspect_ratio string

resolution string

thinking_level string