要点
任务以 failed 结束、没有图片时，先看 failure.type。类型为 declined，说明原因在请求本身：提示词或原始图片因内容规则被拒绝，或者模型回复的是文字而不是图片。这不是 HTTP 错误：请求先以 202 被接收，之后才被判定为失败。同样的请求会得到同样的结果，所以请调整提示词或原始图片，再用新的幂等键发送新请求。失败的请求不会扣费：金额会自动退回余额。
为什么请求被接收了，
图片是异步生成的：请求先被接收并扣费，生成在这之后才开始。最终没有得到图片时，任务以 failed 结束。失败分两种：原因在服务一侧的是 error，原因在请求本身的是 declined。本文讲后一种，它的错误码里有三个：
- 内容规则。提示词或参考图因内容规则被拒绝，错误码是
content_policy；原始图片被拒绝，则是source_image_rejected。 - 模型回复了文字。错误码是
no_image_output：例如模型用文字描述了图片的样子，或者提示词引用了一张没有附上的图片。
被拒绝的请求
请求先被接收：POST /images/generate 返回 202，金额在这时扣除，并出现在 cost 字段里。拒绝是之后才出现的：GET /creations/{id} 返回 200，但状态是 failed，这是任务的结果，而不是查询出了错。
{
"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"status": "queued",
"task_id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"cost": 0.02
}
{
"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"status": "failed",
"error": "The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt.",
"failure": {
"type": "declined",
"code": "content_policy",
"retryable": false
}
}
failure 对象只在 failed 时才有，请当作可选字段。error 字符串是英文的展示文本，措辞可能变化：请依据 failure.type 和 failure.code 编写逻辑，遇到不认识的错误码，就按 failure.type 处理。
类型为 declined 时，同样的请求会得到同样的结果，所以要先调整请求：
content_policy：请调整提示词，或换一张图片。no_image_output：请写明所需的图片，或附上提示词所指的图片。source_image_rejected：请换一张图片。reference_unavailable和invalid_request：参考图已不可用，或请求不能按这种形式执行。请重新上传文件，或修正请求。
类型为 error 时，原因在服务一侧（timeout、unavailable、reference_fetch_failed、internal）：只要 retryable 不等于 false，就可以用新的幂等键再发一次。完整列表见错误码。
在代码里这样读取响应：
CREATION_ID="5b0214ae-9e39-460a-820a-f6ae3e24400b" curl --fail-with-body --max-time 20 \ "https://api.rendergrid.io/ api/ public/ v1/ creations/ $CREATION_ID" \ -H "Authorization: Bearer $RENDERGRID_API_KEY"
import os import requests API = "https://api.rendergrid.io/ api/ public/ v1" creation_id = "5b0214ae-9e39-460a-820a-f6ae3e24400b" key = os.environ["RENDERGRID_API_KEY"] response = requests.get( f"{API}/creations/{creation_id}", headers={"Authorization": f"Bearer {key}"}, timeout=(5, 20), ) response.raise_for_status() creation = response.json() if creation["status"] == "failed": # failure 请当作可选字段 failure = creation.get("failure") or {} if failure.get("type") == "declined": # 原因在请求本身：先改提示词或原始图片，再用新的幂等键发送新请求 print("declined:", failure.get("code")) elif failure.get("type") == "error" and failure.get("retryable") is not False: # 原因在服务一侧：可以用新的幂等键再发一次 print("error:", failure.get("code"))
// Node.js 22+，文件扩展名为 .mjs const API = "https://api.rendergrid.io/ api/ public/ v1"; const id = "5b0214ae-9e39-460a-820a-f6ae3e24400b"; const response = await fetch(`${API}/creations/${id}`, { headers: { Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}` }, signal: AbortSignal.timeout(20_000), }); if (!response.ok) { const body = await response.text(); throw new Error(`HTTP ${response.status}: ${body}`); } const creation = await response.json(); if (creation.status === "failed") { // failure 请当作可选字段 const failure = creation.failure ?? {}; if (failure.type === "declined") { // 原因在请求本身：先改提示词或原始图片，再用新的幂等键发送新请求 console.log("declined:", failure.code); } else if (failure.type === "error" && failure.retryable !== false) { // 原因在服务一侧：可以用新的幂等键再发一次 console.log("error:", failure.code); } }
被拒绝的请求
会。失败的请求不会扣费：金额在接收请求时扣除，失败后自动退回余额，declined 和 error 两种类型都一样。错误本身并不确认退款，请在“余额”页面和控制台的交易记录中查看。成功率的统计不把被拒绝的请求算作失败，而是单独标出。更多见文章“请求失败不收费：按张付费是怎样运作的”。
怎样改写
如果你确定请求没有问题，就改写它：原样重发没有意义，因为同样的请求会得到同样的结果。
新的尝试是新请求，要用新的幂等键：原来的幂等键不会重新启动已经 failed 的任务。它是一次新的付费操作，之前那笔费用会自动退回。
- 写明画面本身。说出主体、数量、背景、光线和位置，不要写“像上一张那样”：文档把“提示词引用了未附上的图片”列为
no_image_output的一种情形。 - 附上提示词所指的图片。把它作为参考图传入，并在提示词里写明要做的编辑：提示词是必填的，即使已有参考图。
下面三条提示词按第一种写法写成，都写明了主体和数量、背景、光线、取景和不该出现的东西。它们是发给 Nano Banana 2.1 的普通、无害的请求，每条只发送了一次，都得到了图片，没有被拒绝。我们没有检验过别的写法。
这张图片的提示词
浅色桌上是一只简单白瓷碗，碗里放三个橙子，其中一个略高。中性背景安静，左侧柔和日光呈现果皮纹理。碗完整居中，外缘留白，不放其他物件。不出现文字、标志、人物或水印。
Nano Banana 2.1
nano-banana-2.1 · 1K · 1:1 · $0.02
Nano Banana 2.1，1K，1:1，一次尝试。白瓷碗里能清楚数出三个橙子，一个叠在另外两个上面；三个橙子之间还露出一小块橙色的果皮，无法确认那里是否还有第四个橙子，所以不能确定橙子恰好是三个。提示词只要求其中一个“略高”，画面里最上面的这个高出许多，是明显叠放在上面。光线从左侧来，碗在右侧落下一道柔和的影子，与提示词一致，果皮的纹理清晰可见。提示词要求碗居中：画面里碗连同橙子左右居中，但整体略低于画面中心，四周都留有空白。没有文字、标志、人物或水印。
这张图片的提示词
奶油色背景前，一只小透明玻璃花瓶插着三朵雏菊，水中花茎可见，花瓣彼此分明。散射光在右侧留下浅影。花瓶与所有花朵完整放入方形画面，周围宽松。不出现文字、标志、人物或水印。
Nano Banana 2.1
nano-banana-2.1 · 1K · 1:1 · $0.02
Nano Banana 2.1，1K，1:1，一次尝试。三朵白色雏菊插在透明的小玻璃瓶里，每朵花的花瓣都分得清，水中的花茎也能看到。容器是短颈窄口的小瓶子。散射的光在瓶子右侧留下一道浅影，与提示词一致；背景上另有几道柔和的亮带，是提示词没有写到的。瓶子和花朵完整地放在方形画面里，四周留白宽松，整体略低于画面中心。没有文字、标志、人物或水印。
这张图片的提示词
两本纯色布面精装书合拢叠放，封面和书脊均为空白，旁边一颗木球，底面浅灰。镜头略俯视，柔光下织纹与木纹分明。物件集中在中央，边缘全部保留。不出现文字、标志、人物或水印。
Nano Banana 2.1
nano-banana-2.1 · 1K · 1:1 · $0.02
Nano Banana 2.1，1K，1:1，一次尝试。两本合上的布面精装书叠放，两本没有完全对齐，封面和书脊上都没有文字；布面的织纹和木球上的年轮状木纹都能看清，柔和的光让影子的边缘很淡。提示词要求镜头“略俯视”，画面里的视角要高得多：上面一本的整个封面都清楚可见，是从较高的角度拍摄的，但不是正上方俯拍。书和木球集中在画面中央，四边都没有被裁切。除此之外没有发现明显的缺陷。
什么情况下
- 这不是绕过规则的办法。如果请求不符合内容规则，我们不保证下一次能通过，也不说明怎样绕过。
- 三张图片不是检验。每条提示词只发送了一次，展示的是写法，不是通过率。
- 原因不在文字时，改提示词没有用。
source_image_rejected和reference_unavailable要靠换图或重新上传文件。 - 请求有误是另一回事。缺少
prompt等问题会在接收之前返回400 ERR_INVALID_REQUEST：生成不会开始，也不会扣费。
常见问题解答
API 没有返回图片，该怎么办？
GET /creations/{id} 查询任务。状态是 failed 时，读取 failure.type 和 failure.code：declined 先改提示词或原始图片，error 在 retryable 不等于 false 时可以用新的幂等键再发一次。被拒绝的请求要付费吗？
可以把同一个请求再发一次吗？
拒绝会作为 HTTP 错误返回吗？
ERR_CONTENT_POLICY 是保留的错误码：因内容规则被拒绝时，返回的是状态为 failed、failure.code 为 content_policy 的任务。请求本身有误时返回的才是 HTTP 错误，例如 400 ERR_INVALID_REQUEST，这时不扣费。来源
- 文档：错误码两种类型、错误码和退款。
- 文档：任务与状态
failed状态和任务的响应。 - 文档：生成图片接收请求时扣费和
cost字段。 - 文档：重试不重复扣费幂等键和失败之后的新请求。
- 请求失败不收费：按张付费是怎样运作的失败的请求会自动退款。
- 本文的三张图片Nano Banana 2.1，1K，1:1，每条提示词一次尝试；提示词在图片旁。
