06API 基础
生成图片
一次请求生成一张图片。写明要生成的内容,选择模型和宽高比,再通过轮询或 Webhook 获取结果。
这个模型并不支持所有分辨率和宽高比:示例中使用的是它支持的那些。
请求
/images/ generate发送 JSON,并带上请求头 Authorization 和 Content-Type: application/json。每生成一张新图片都使用新的 X-Idempotency-Key,重试同一个请求时则沿用之前的:这样就不会重复付费(了解更多)。
# 需要 bash、curl 和 uuidgen。每个请求使用一个幂等键。 IDEMPOTENCY_KEY="$(uuidgen)" || exit 1 curl --fail-with-body --max-time 30 \ -X POST https://api.rendergrid.io/ api/ public/ v1/ images/ generate \ -H "Authorization: Bearer $RENDERGRID_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Idempotency-Key: $IDEMPOTENCY_KEY" \ -d '{ "model": "nano-banana-pro", "prompt": "大理石上的陶瓷杯,柔和的窗光", "resolution": "2K", "aspect_ratio": "16:9" }'
import os import uuid import requests key = os.environ["RENDERGRID_API_KEY"] payload = { "model": "nano-banana-pro", "prompt": "大理石上的陶瓷杯,柔和的窗光", "resolution": "2K", "aspect_ratio": "16:9", } response = requests.post( "https://api.rendergrid.io/ api/ public/ v1/ images/ generate", headers={ "Authorization": f"Bearer {key}", "X-Idempotency-Key": str(uuid.uuid4()), }, json=payload, timeout=(10, 120), ) response.raise_for_status() creation = response.json() # 202: {id, status, task_id, cost} print(creation["id"])
// Node.js 22+,文件扩展名为 .mjs import { randomUUID } from "node:crypto"; const API = "https://api.rendergrid.io/ api/ public/ v1"; const response = await fetch(`${API}/images/generate`, { method: "POST", headers: { Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}`, "Content-Type": "application/json", "X-Idempotency-Key": randomUUID(), }, body: JSON.stringify({ model: "nano-banana-pro", prompt: "大理石上的陶瓷杯,柔和的窗光", resolution: "2K", aspect_ratio: "16:9", }), signal: AbortSignal.timeout(120_000), }); if (response.status !== 202) { const body = await response.text(); throw new Error(`HTTP ${response.status}: ${body}`); } // 202 响应:{id, status, task_id, cost} const creation = await response.json(); console.log(creation.id);
{
"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"status": "queued",
"task_id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"cost": 0.04
}- id
- 任务 id。用它获取结果:任务与状态。
- status
- 刚接收时为
queued。 - task_id
- 任务 id。请求
GET /creations/时请代入{id} id。 - cost
- 为这张图片扣除的金额,单位为美元:精确到小数点后四位的数字。
202 Accepted 表示“请求已接收”,而不是“图片已就绪”。
构建请求
构建请求体并查看价格。每个模型都有各自的分辨率和宽高比。灰色选项无法选择:点击它,就能看到 API 拒绝时返回的响应,且不会扣费。
14 / 20,000 个字符。清空文字,就能看到 API 如何拒绝空提示词。
未指定分辨率时为 2K。
灰色的宽高比,这个模型无法生成。未指定宽高比时为 1:1;auto 表示由模型选择。
{
"model": "nano-banana-pro",
"prompt": "大理石上的陶瓷杯,柔和的窗光",
"resolution": "2K",
"aspect_ratio": "16:9"
}这张图片的价格:$0.04。 失败的请求免费:金额会立即退回余额。
请求字段
| 字段 | 类型 | 说明 |
|---|---|---|
model必选 | string | 你账号的模型目录中的模型 id:模型与参数。 |
prompt必选 | string | 图片或编辑内容的说明,最多 20,000 个字符。始终需要提供,即使已有参考图。提示词为空或只有空格时,响应为 400,不会扣费。 |
aspect_ratio可选 | string | 宽高比,例如 16:9。不传该字段时为 1:1——缺少该字段不等于 auto。可用的值取决于模型。 |
resolution可选 | string | 1K、2K 或 4K,不区分大小写。可用的值和默认值取决于模型。 |
output_format可选 | string | 结果文件的格式:png 或 jpg。省略该字段时,返回模型的原生格式。 |
image_file_ids可选 | string[] | 最多 14 个来自 POST /uploads 的 file_id。仅文本生成时不要传。详见 参考图。 |
image_file_id可选 | string | 一个 file_id。可代替 image_file_ids,用于单张参考图;不要同时传两者。 |
image_urls可选 | string[] | 1 到 14 张图片的公开地址。不要与 file_id 同时使用:只选择其中一组字段。 |
webhook_url可选 | string | 用于就绪通知的公开 HTTPS 地址,最多 2,048 个字符:Webhook。 |
图片大小由 resolution 决定:它是模型的尺寸档位,而不是精确的像素数。不接受 width 和 height 字段。如果需要精确尺寸,请查看所得文件的尺寸。
每个请求生成一张图片。需要更多时,请使用不同的幂等键发送多个请求,并保持在账号限额之内(见限额)。
扣费前会检查什么
这些检查在扣费之前进行。如果 API 返回 400 ERR_INVALID_REQUEST,余额不会变化,error.details 中会说明需要修正什么。
- 缺少
prompt,或其为空、只包含空格。 - 所选模型不支持
resolution或aspect_ratio的取值——details.supported中会返回可用值的列表。 - 传入了大于 1 的
n,或传入了width、height。 - 包含蒙版(
mask、mask_file_id):不支持蒙版。请把原图作为参考图传入,并在提示词中写明编辑内容。 - 同时使用两类参考图(例如
image_file_ids和image_urls),或参考图超过 14 张。 webhook_url地址无效或被禁止。
价格与扣费
价格取决于模型和分辨率。例如,Nano Banana Pro 在 1K 下为 $0.04,在 4K 下为 $0.07,GPT Image 2 则为每张 $0.02。所有价格见“模型与参数”页面和 GET /models 的响应。
金额在接收请求时、开始处理之前扣除,并通过 cost 字段返回。可以用 GET /balance 请求查询余额。
请求失败不收费:金额会立即退回余额。