图片生成失败说明

即使请求格式正确，图片生成也可能失败。常见原因包括供应商安全策略、提示词目标不支持、参考图问题、临时容量不足或速率限制。Pixapi 会尽量让 API 响应、任务状态和积分流水保持一致，方便你的产品给用户明确反馈。

快速排查

现象	常见原因	建议处理
返回安全策略或审核相关提示	提示词或参考图触发供应商安全检查	移除受限内容，简化提示词，用更安全的描述重试。
没有图片，或只返回文本	模型没有返回图片部分	检查响应 parts、请求的输出模态、提示词复杂度和模型能力。
超时、503 或供应商不可用	供应商临时容量、网络或上游错误	使用有限次数的退避重试，并先保持同一 payload 做一次验证。
上传或参考图报错	格式不支持、文件过大、文件损坏或 URL 不可访问	使用 PNG、JPEG 或 WebP，控制文件大小，并确认 Pixapi 可访问图片 URL。
429 或速率限制提示	账户、模型或供应商侧触发限流	使用带抖动的退避策略，把非紧急任务排队，不要密集重试。
insufficient_credits	生成开始前余额不足	引导用户购买积分；这不是生成失败后的积分退还场景。

常见原因

安全策略和受限内容

图片供应商可能会拦截包含露骨色情、血腥暴力、仇恨或骚扰、自残、违法行为，或不当未成年人相关内容的提示词和参考图。这类策略可能发生在生成阶段，而不只是请求校验阶段。

去水印和版权内容

去除水印、复刻受保护角色、复制知名 IP、或模仿名人/公众人物的请求，可能被拒绝或无法返回可用图片。建议改成原创概念、授权素材，或更泛化的视觉风格描述。

提示词过于复杂

过长提示词、相互冲突的指令、大量文字渲染要求或过多主体，都可能导致模型只返回文本、部分输出或没有图片。先保留主体、风格、构图和输出要求，再逐步添加细节。

参考图问题

图片编辑和图生图请求依赖输入素材。请确认图片 URL 可访问、文件没有损坏、格式受支持。如果签名 URL 很快过期，请重新上传图片或使用有效期更长的 URL。

供应商临时问题

供应商容量、限流和上游超时都可能间歇发生。生产环境中建议只做少量指数退避重试，并带随机抖动。第一次复测时尽量保持模型、payload 和参考图不变，避免排查信号被多个变量打散。

已退还积分

如果积分已扣除或预留，但图片生成任务在产生可计费结果前失败，Pixapi 会把受影响的积分退还到账户。积分流水中这类记录会显示为 已退还。

你可以在 额度明细 查看已退还的积分记录。已退还表示余额已恢复，但不代表原提示词不做调整就一定能成功。

联系支持前建议提供

请提供 request id 或 task id、模型 id、时间、脱敏后的提示词、输入图片格式和大小、响应错误码，以及积分是否已退还。这能帮助支持团队更快区分安全策略、payload 问题、供应商异常和计费对账问题。