07API 基础
参考图
向模型提供你的图片,并说明要对它做什么:保留商品、更换背景、延续风格。参考图可以通过上传文件提供,也可以通过链接传入。
这个模型并不支持所有分辨率和宽高比:示例中使用的是它支持的那些。
如何传入参考图
参考图是可选的:没有参考图时,模型只根据文本生成。如果需要参考图,请只选择一类字段:事先上传的文件,或图片地址。
| 方式 | 请求字段 | 适用情况 |
|---|---|---|
| 不使用参考图 | 不传 | 根据提示词从零开始生成 |
| 上传的文件 | image_file_ids(最多 14 个)或 image_file_id | 文件在你的磁盘上;同一张参考图要用于多个请求 |
| 图片地址 | image_urls(最多 14 个) | 图片已经可以通过公开链接访问 |
请求体
{
"model": "nano-banana-pro",
"prompt": "保留这盏灯,把它放在明亮的窗台上",
"resolution": "2K",
"image_file_ids": ["ea7b3c89972d3657"]
}{
"model": "nano-banana-pro",
"prompt": "保留这盏灯,把它放在明亮的窗台上",
"resolution": "2K",
"image_urls": ["https:// cdn.example.com/ products/ lamp.png"]
}不要混用两种方式。如果同一个请求里既有 image_urls 又有 file_id,API 会在扣费前返回 400 ERR_INVALID_REQUEST。不接受 image、image_url、image_input 和 input_urls 字段。
上传文件
POST
/uploads以 multipart/form-data 发送文件:file 字段是文件本身,kind 字段的值为 image。响应中会返回 file_id,把它代入生成请求即可。
curl --fail-with-body --connect-timeout 10 --max-time 120 \ -X POST https://api.rendergrid.io/ api/ public/ v1/ uploads \ -H "Authorization: Bearer $RENDERGRID_API_KEY" \ -F "file=@lamp.png;type=image/png" \ -F "kind=image"
import os import requests key = os.environ["RENDERGRID_API_KEY"] with open("lamp.png", "rb") as image: response = requests.post( "https://api.rendergrid.io/ api/ public/ v1/ uploads", headers={"Authorization": f"Bearer {key}"}, files={"file": ("lamp.png", image, "image/png")}, data={"kind": "image"}, timeout=(10, 120), ) response.raise_for_status() upload = response.json() print(upload["file_id"], upload["expires_at"])
// Node.js 22+,文件扩展名为 .mjs import { readFile } from "node:fs/promises"; const bytes = await readFile("lamp.png"); const file = new Blob([bytes], { type: "image/png" }); const form = new FormData(); form.append("file", file, "lamp.png"); form.append("kind", "image"); const API = "https://api.rendergrid.io/ api/ public/ v1"; const key = process.env.RENDERGRID_API_KEY; const response = await fetch(`${API}/uploads`, { method: "POST", headers: { Authorization: `Bearer ${key}` }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) { const body = await response.text(); throw new Error(`HTTP ${response.status}: ${body}`); } const upload = await response.json(); console.log(upload.file_id, upload.expires_at);
{
"file_id": "ea7b3c89972d3657",
"url": "https:// cdn.rendergrid.io/ user_uploads/ example.png",
"expires_at": "2026-10-14T12:00:00+00:00"
}- file_id
- 文件 id。归上传它的账号所有。
- url
- 文件副本的地址。它不是永久存储:
expires_at之后不能再使用。 - expires_at
file_id失效的时间:上传后 24 小时。
| 项目 | 规则 |
|---|---|
| 格式 | PNG、JPEG 和 WebP。不接受 GIF 和 BMP |
| 大小 | 每个文件最大 25 MiB(26,214,400 字节) |
| 有效期 | file_id 的有效期为 24 小时。在请求中使用不会延长有效期 |
| 重新上传 | 同一个文件再次上传,会得到新的 file_id,同样有效 24 小时 |
| 资金 | 上传不会从余额中扣除任何金额 |
| 每日限额 | 自行注册且尚未充值的账号,按 UTC 计每天最多使用 100 张参考图:上传的文件和 image_urls 中的地址合并计算。首次充值后不再有此限额 |
发送前检查文件
下面是 API 对最常见文件的响应。所有拒绝都会立即返回,在生成开始之前。
选择文件我们会为每个示例展示 API 的真实响应
点击“发送文件”——响应会显示在这里。
用地址代替文件
如果图片已经在互联网上,就不必上传:把链接传入 image_urls 即可。图片由我们的服务器下载,因此链接需要能在外部无需登录直接打开。
- 公开的
http://或https://地址,端口为 80 或 443。内部网络的地址和内含用户名与密码的链接不可用。 - 不会跟随重定向:请填写图片的最终地址。
- 返回内容应当是不超过 25 MiB 的 PNG、JPEG 或 WebP 图片。
- 来源需要响应迅速:下载时间有限制。如果来源很慢或受密码保护,请自行下载文件,再通过
POST /uploads上传。
如何准备参考图
- 在
prompt中说明要保留什么、更改什么。模型能看到参考图,但不知道你想用它做什么。 - 一个请求最多 14 张参考图。
- 超过 7 MiB 或长边超过 4,096 像素的参考图,在处理前可能会被缩小或重新压缩。带透明背景的大图,背景可能会变成白色。
- 请自行保存原件:
file_id在上传后 24 小时内有效;已存储的文件会在最后一次上传 48 小时后删除。 - 不支持蒙版(inpainting)。请把原图作为参考图传入,并用文字写明要做的编辑。
可能出什么问题
这些拒绝都发生在扣费之前:余额不会变化。
| 发生了什么 | API 响应 | 怎么办 |
|---|---|---|
| 文件超过 25 MiB | 400 ERR_INVALID_REQUEST, “File exceeds the maximum allowed size”, details.max_bytes | 压缩文件或缩小图片 |
| GIF、BMP 或其他格式 | 400 ERR_INVALID_REQUEST, “Unsupported image format. Supported formats: PNG, JPEG, WebP.” | 将图片另存为 PNG、JPEG 或 WebP |
| 文件为空,或不是图片 | 400 ERR_INVALID_REQUEST, “Uploaded file is empty” 或 “File content does not match the declared media kind” | 检查文件:扩展名是 .png 并不代表它就是图片 |
file_id 已过期或不可用 | 400 ERR_INVALID_REQUEST, details.reason: reference_unavailable, details.input_index, details.retryable: false | 重新上传文件,并代入新的 file_id |
| 链接无法下载 | 422 ERR_INPUT_FETCH_FAILED, details.retryable, details.input_index | 仅当 retryable: true 时才重试。否则请修正链接,或自行上传文件 |
| 参考图超过 14 张,或同时使用两种方式 | 400 ERR_INVALID_REQUEST, details.errors | 保留最多 14 张参考图,并只使用一类字段 |
| 请求中包含蒙版 | 400 ERR_INVALID_REQUEST, details.fields: ["mask_file_id"] | 去掉蒙版,把原图作为参考图传入,并用文字写明要做的编辑 |
| 每日上传限额已用尽 | 429 ERR_RATE_LIMIT, “Daily upload limit reached. Add funds to your account to lift it.”, details.limit, details.window = "1d", details.retry_after 以及请求头 Retry-After | 充值余额——限额即会解除——或等到按 UTC 计算的下一天 |
如果参考图在接收请求之后才变得不可用,任务会以 failed 状态结束,failure.code 为 reference_unavailable 或 reference_fetch_failed。详见“错误码”页面。
请求失败不收费:金额会立即退回余额。
常见问题
最多可以传入多少张参考图?
一个请求最多 14 张:
image_file_ids 和 image_urls 中各有 1 到 14 个值。同一个 file_id 可以用于多个请求吗?
可以,在有效期内即可:上传后 24 小时。在请求中使用不会延长有效期。需要新的有效期时,请重新上传文件,获取新的
file_id。支持 GIF 吗?
不支持。只接受 PNG、JPEG 和 WebP——上传和
image_urls 都是如此。为什么上传参考图会返回 429?
上传文件和提供链接哪个更好?
如果图片已经发布,用链接更省事。上传文件更可靠:它不取决于对方服务器的速度,也不取决于链接是否有密码保护。