图片幂等提交与原请求恢复

第一次提交就携带 Idempotency-Key，并在发送前保存它。 无法给先前未携带 key 的请求补加幂等保护。提交响应丢失后，使用同一个 key 做认证 GET 查询，不要创建替代生成。

覆盖范围

按接口接入，不维护模型白名单：当前和未来使用以下接口的图片模型自动获得保护，包括 Gemini、GPT Image、Seedream、Grok 和 Midjourney。幂等保护不会让原本不支持的模型/接口组合变成可用。

• POST /v1/images/generations、/v1/images/generations/async。
• POST /v1/images/edits、/v1/images/edits/async、/v1/edits、/v1/images/variations。
• /v1/midjourney/generations 及其 /imagine 别名、旧版 /mj/submit/* 路径。
• 为覆盖多模态出图，带 key 的 POST /v1/chat/completions、/v1/responses，以及 /v1/models/{model}:generateContent 原生 Gemini 路径也采用相同规则，包括 :predict、:streamGenerateContent。这些接口的纯文本请求携带 key 时同样生效。流式输出会缓冲后持久化再返回，不再逐段推送，建议使用非流式请求。

不携带该请求头时保留原有行为。Seedance 使用独立的视频幂等契约。

请求头、作用域与冲突

Authorization: Bearer YOUR_API_KEY
Idempotency-Key: image-order-123-attempt-1
Content-Type: application/json

key 为 8–128 个可见 ASCII 字符，不含空格。作用域是提交账户，覆盖全部受保护接口。同账户另一把有效 API key 可以找回回执和原响应；仍检查账户状态、密钥吊销/过期与 IP 限制。额度耗尽的 key 仍能恢复原请求，首次执行仍须通过正常额度检查。APIMaster 与其他服务的账户、key 和回执相互独立，跨服务不会去重。

同 key、同请求并发或重发只允许一次原执行，不会再次生成和计费。已有成功响应时原样回放并带 Idempotency-Replayed: true；处理中或结果不明时返回 HTTP 202 与原回执。

同 key 改变接口路径、模型、正文、有效分组或显式固定渠道，返回 HTTP 409、error.code = idempotency_conflict。JSON 正文按字节精确比较，包括空白、字段顺序、数字写法和省略/显式字段；请保留首次正文。GET 恢复不需要正文。

multipart 允许 boundary 和文件名变化；表单值、上传字段名、文件字节、同字段的文件顺序必须一致。重复的普通字段会被拒绝。不得修改参考图后复用原 key。

回执和原响应至少保留 30 天；当前不自动删除、不自动复用 key。超时或 key 很旧都不授权重新执行。原响应中的图片 URL 有独立有效期，请及时下载。

平台先持久化账户/key 占位，再进入生成和计费。带 key 的请求关闭自动换渠道重试和慢任务并发补发；结果不明时不会内部创建替代生成。这是可选能力：不携带 Idempotency-Key 的请求保留原有 fallback 行为，不具备本页的原提交恢复保证。

不再 POST，直接找回原任务或结果

# 只读查询原提交回执
curl --fail-with-body 'https://apimaster.ai/v1/image-submissions/by-key' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: image-order-123-attempt-1'

# 取回已保存的原 HTTP 正文和状态码
curl --fail-with-body 'https://apimaster.ai/v1/image-submissions/by-key/response' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: image-order-123-attempt-1'

两种 GET 都要求认证，且只读：不创建任务、不生成、不轮询上游、不结算或退款、不重新提交。返回 Cache-Control: no-store、X-Image-Submission-Id 和 X-Original-Request-Id。

回执位于 data。/response 在可用时返回原响应正文和原 HTTP 状态码，否则返回 202 与回执。原响应可能是 data[0].task_id、同步图片 data[].url / b64_json、Midjourney 批次或原生多模态结果。得到原任务 ID 后使用该模型原有的任务 GET 接口和原模型 ID 继续查询。恢复接口不转换结果格式，也不延长原图片链接有效期。

什么情况下才可以创建新尝试

data.status	含义	是否允许替代生成
pending、submitting	原占位/执行仍在处理中	不允许，稍后查原回执
accepted	已保存原成功 JSON 响应；异步任务可能尚未完成	不允许，取原响应后查原任务
acceptance_unknown	无法确认是否接受，包括执行中断或租约过期	不允许，保留 key 和原 request ID 排查
not_accepted	原请求在进入业务、生成和计费逻辑之前已被拒绝	修正原因后，使用新 key

只有以下字段同时成立，才证明可以新建技术尝试：status = not_accepted、acceptance_final = true、new_submission_safe = true、retry_safe = true、billing_final = true、billing_status = final_zero、net_charge = 0。旧 key 始终关联旧回执，不会重新执行。

其他状态返回 billing_status = unverified、billing_final = false、net_charge = null，不承诺账务已结清。任务失败、退款申请、超时或空结果，均不等于提交前未接受，也不能单独证明最终零净扣费；本回执不会从后续失败或退款推导这类保证。

查不到回执返回 404、error.code = submission_not_found、error.retry_safe = false。可能存在原请求竞态、首次未带 key 或功能启用前的历史请求，不等于最终 not_accepted。

结构化错误

• invalid_idempotency_key：key 格式不合法；不说明另一笔原提交的结果。
• idempotency_conflict：key 对应的请求不同，恢复原请求，不要覆盖。
• submission_not_found：暂未查到回执，不授权重发。
• submission_storage_unavailable、submission_claim_unavailable：临时存储或执行占位故障，继续 GET 查询原 key。
• submission_response_too_large：原响应超过 64 MiB 恢复缓冲上限，使用已知原任务 ID 或联系支持，不重新生成。
• 适用适配器中的 do_request_failed、read_response_body_failed、image_generation_timeout：传输、读取或等待故障，不能证明未接受。

HTTP 408/429/5xx 或上游特有错误均不是统一的安全重试信号。响应丢失后，保留原 key、正文、UTC 时间、模型、接口及已收到的 request ID；不要向支持人员发送 API key。

登录后的图片体验页代理

/api/playground/image 会透传调用方提供的 Idempotency-Key 和原回执标识。携带同一个请求头访问 GET /api/playground/image 可查回执；增加 ?submission_response=1 可取原响应正文。带 task_id 的 GET 仍按原任务查询处理。此代理要求登录，不会给未携带 key 的请求自动补建 key。