Nano Banana 2.1 API

POST Base URL: https://api.hiapi.ai /v1/tasks

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称	gemini-nano-banana-2.1
用途	图像生成与参考图编辑
接口	POST /v1/tasks
价格	HiAPI

用 Nano Banana 2.1 创作时装人像与家居场景，也可根据参考照片局部换装。在线试用并查看真实生成案例与编辑前后对照，了解提示词、画幅和分辨率选择，通过 HiAPI 接入图像生成与编辑 API。

生产建议

生产环境建议

生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

摄影场景与图文广告

说明人物或产品、材质、镜头、光线与文字位置，生成适合版位的视觉提案。

promptaspect_ratio

参考照片局部换装

提供原图，逐项说明修改内容与保留内容。

promptimage_input

请求参数

POST https://api.hiapi.ai/v1/tasks

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 API Key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "A fashion editorial photograph on a sunlit white-stucco terrace above the Mediterranean, shot at eye level with a 50mm lens. One adult woman in her late twenties is walking naturally toward the camera at the right-center of the composition, her head turned slightly toward the sea with a relaxed confident expression. She wears an oversized ivory linen blazer over a deep burgundy silk camisole, high-waisted navy tailored trousers, and simple leather sandals. Wind lifts a few strands of her dark shoulder-length hair and gently moves the blazer hem. A cobalt-blue glazed ceramic bench occupies the left foreground; beyond it, crisp ivory architecture frames a bright turquoise sea and a small distant headland. Directional late-afternoon sunlight reveals real skin texture, linen weave and silk highlights, with clean architectural shadows and controlled reflections. Rich but restrained cobalt, burgundy, ivory and warm skin tones, sophisticated magazine photography, believable proportions and hands, beautifully resolved clothing, candid physical movement, subtle film grain. The woman is the clear visual focus, with the surrounding terrace providing depth. No lettering, no logos, no watermark, no illustration, no CGI appearance, no airbrushed plastic skin.",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "A fashion editorial photograph on a sunlit white-stucco terrace above the Mediterranean, shot at eye level with a 50mm lens. One adult woman in her late twenties is walking naturally toward the camera at the right-center of the composition, her head turned slightly toward the sea with a relaxed confident expression. She wears an oversized ivory linen blazer over a deep burgundy silk camisole, high-waisted navy tailored trousers, and simple leather sandals. Wind lifts a few strands of her dark shoulder-length hair and gently moves the blazer hem. A cobalt-blue glazed ceramic bench occupies the left foreground; beyond it, crisp ivory architecture frames a bright turquoise sea and a small distant headland. Directional late-afternoon sunlight reveals real skin texture, linen weave and silk highlights, with clean architectural shadows and controlled reflections. Rich but restrained cobalt, burgundy, ivory and warm skin tones, sophisticated magazine photography, believable proportions and hands, beautifully resolved clothing, candid physical movement, subtle film grain. The woman is the clear visual focus, with the surrounding terrace providing depth. No lettering, no logos, no watermark, no illustration, no CGI appearance, no airbrushed plastic skin.",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 API Key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "A fashion editorial photograph on a sunlit white-stucco terrace above the Mediterranean, shot at eye level with a 50mm lens. One adult woman in her late twenties is walking naturally toward the camera at the right-center of the composition, her head turned slightly toward the sea with a relaxed confident expression. She wears an oversized ivory linen blazer over a deep burgundy silk camisole, high-waisted navy tailored trousers, and simple leather sandals. Wind lifts a few strands of her dark shoulder-length hair and gently moves the blazer hem. A cobalt-blue glazed ceramic bench occupies the left foreground; beyond it, crisp ivory architecture frames a bright turquoise sea and a small distant headland. Directional late-afternoon sunlight reveals real skin texture, linen weave and silk highlights, with clean architectural shadows and controlled reflections. Rich but restrained cobalt, burgundy, ivory and warm skin tones, sophisticated magazine photography, believable proportions and hands, beautifully resolved clothing, candid physical movement, subtle film grain. The woman is the clear visual focus, with the surrounding terrace providing depth. No lettering, no logos, no watermark, no illustration, no CGI appearance, no airbrushed plastic skin.",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

要调用的模型 ID。

示例 gemini-nano-banana-2.1

input object 必填

图像生成与编辑参数。

prompt string 必填

描述画面或对参考图片提出修改要求；长度为 1–20000 个字符。

image_input string[] 可选

用于编辑或融合的参考图片 URL，最多 10 张；JPEG、PNG、WebP，每张不超过 30 MB，链接须可公开访问。

aspect_ratio enum 可选

控制画面比例；auto 根据提示词与参考图选择画幅。

默认 auto 可选值: 1:12:33:21:44:13:44:34:55:41:88:19:1616:921:9auto

resolution enum 可选

输出分辨率档位，实际宽高随画幅变化。

默认 1K 可选值: 1K2K4K

output_format enum 可选

图片文件格式；PNG 不保证透明背景。

默认 jpg 可选值: jpgpng

callback object 可选

任务终态通知配置。

url string 必填

接收任务通知的 HTTPS 地址。

when enum 可选

通知触发时机。

默认 final 可选值: final

用例示例

海岸时装摄影

通过人物动作、服装材质、光线与环境层次，生成一张横向摄影提案。

请求体

{
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "A fashion editorial photograph on a sunlit white-stucco terrace above the Mediterranean, shot at eye level with a 50mm lens. One adult woman in her late twenties is walking naturally toward the camera at the right-center of the composition, her head turned slightly toward the sea with a relaxed confident expression. She wears an oversized ivory linen blazer over a deep burgundy silk camisole, high-waisted navy tailored trousers, and simple leather sandals. Wind lifts a few strands of her dark shoulder-length hair and gently moves the blazer hem. A cobalt-blue glazed ceramic bench occupies the left foreground; beyond it, crisp ivory architecture frames a bright turquoise sea and a small distant headland. Directional late-afternoon sunlight reveals real skin texture, linen weave and silk highlights, with clean architectural shadows and controlled reflections. Rich but restrained cobalt, burgundy, ivory and warm skin tones, sophisticated magazine photography, believable proportions and hands, beautifully resolved clothing, candid physical movement, subtle film grain. The woman is the clear visual focus, with the surrounding terrace providing depth. No lettering, no logos, no watermark, no illustration, no CGI appearance, no airbrushed plastic skin.",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}

获取结果

提交成功后立即返回 taskId（不等待生成完成）。
生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
status=success 后，从返回的 output[].url 下载生成的图片。
如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

如何在生成与编辑之间切换？

只写提示词即可生成图片。添加参考图片后，描述需要修改的内容与必须保留的细节；两种用法使用同一个模型 ID。每次任务独立处理，需要继续编辑时再次提供上一张结果。

参考图片怎样配合提示词使用？

最多添加 10 张 JPEG、PNG 或 WebP 图片。说明每张图片提供的主体、背景或风格，再列出保留项。图片 URL 必须可以公开访问；API 单张图片不超过 30 MB。

auto 画幅会怎样选择？

auto 让模型根据提示词和参考图片选择画幅。需要海报或广告版位时，直接选择明确的比例；分辨率档位不代表固定的宽高像素。比例是构图目标，实际像素可能略有差异，尤其是 1:8 与 8:1；固定版位请核对输出文件尺寸后再裁切。

怎样提高海报文字的可读性？

将需要出现的文字逐句写出，说明标题、标签和副标题的位置，并限制额外文字。成片后逐字核对，尤其是小字号与较长段落。

可以生成透明背景或一次多张图片吗？

当前每次任务生成一张 JPG 或 PNG 图片，没有透明背景开关或批量张数参数。PNG 是文件格式，不保证透明背景。

如何获取和保存结果？

提交后保存 taskId，通过 GET /v1/tasks/:id 查询状态，成功后读取 output[].url。也可设置 callback.url 接收终态通知；长期使用的结果请及时保存。