图像生成为什么需要独立的 Gateway 抽象参数、重试与幂等设计开篇一个generateImage()可能不是一次供应商请求调用方看到一次generateImage()供应商侧却未必只收到一次请求。AI SDK 的官方文档明确说明当n超过模型单次生成上限时SDK 会自动拆成多次并行调用API 还提供maxRetries当前参考页给出的默认值是 2。一个看似原子的 SDK 调用已经可能展开成多次有独立费用和失败状态的供应商 Attempt。图像生成还多了尺寸、宽高比、参考图、mask、Seed、质量、风格、输出格式和二进制产物。若统一层只做字段重命名它会在最危险的位置制造“看似兼容”参数被忽略、重试重复计费、fallback 输出不符合用户约束取消按钮也可能只停止等待而没有停止供应商执行。AI SDK 的generateImage展示了统一入口的价值也明确保留providerOptions、size/aspectRatio 互斥能力、seed、mask、abortSignal和多调用拆分。官方文档一个生产级自有网关应延续这个原则统一共同语义同时把一次用户意图展开后的每个 Attempt 和 Artifact 暴露为可审计对象。核心结论用户 Job、供应商 Attempt 和图片 Artifact 是三个不同实体幂等键也应分层。Canonical request 只应包含跨模型语义稳定的字段特殊能力放入 provider options。路由前必须做 capability negotiation不能把不支持参数静默丢弃。自动重试必须区分“确定未执行”“执行状态未知”和“已完成响应丢失”。Cost Ledger 记录每次供应商 Attempt而不是只记录最终展示给用户的图。一、三层对象模型这条链路不是一对一一个 User Image Job 可以展开成多个 Provider Attempt每个 Attempt 又可以产生一个或多个 Artifact。审核、转码和缩略图会继续派生新 Artifact最终只有被选中的对象进入交付集合。Image Job用户意图的稳定对象prompt、编辑输入、期望数量、能力要求、预算、保留策略、租户和业务幂等键。Provider Attempt一次实际供应商请求模型、映射后参数、请求 ID、开始/结束、状态、错误、计费、fallback 原因。Artifact任何二进制产物供应商输出、原图、审核图、缩略图、水印图和最终交付图。每个 Artifact 有哈希、MIME、尺寸、存储位置、来源 Attempt、派生父对象和删除状态。将三者混成一张generations表会导致重试后无法解释哪个账单对应哪个图片。网关至少要为每次调用返回一份内部执行回执{job_id:img_job_01,attempts:[{attempt_id:att_01,trigger:initial,provider:provider-a,credential_type:byok,status:unknown_after_send,provider_request_id:req_xxx,estimated_cost_usd:0.04},{attempt_id:att_02,trigger:manual_retry_after_reconciliation,provider:provider-b,credential_type:system,status:succeeded,artifact_ids:[art_01]}],delivery_artifact_ids:[art_02]}这份回执不是为了把内部实现暴露给终端用户而是让客服、账单、删除任务和事故复盘能够回答发送了几次、谁实际执行、用了谁的凭证、哪些图片被保存或交付。二、Canonical RequestexporttypeImageJobRequest{userRequestId:string;prompt:string;count:number;operation:generate|edit|variation;inputArtifacts?:string[];maskArtifact?:string;output:({aspectRatio:string;width?:never;height?:never;}|{aspectRatio?:never;width:number;height:number;}){format?:png|jpeg|webp;transparent?:boolean;};reproducibility?:{seed?:number;strict?:boolean;};policy:{maxCostUsd:number;allowedModels?:string[];artifactRetention:ephemeral|standard|custom;inferenceDataPolicy:required_zdr|disallow_training|standard;};providerOptions?:Recordstring,unknown;};字段必须分三种Required semantic供应商不支持就不能路由Preferred semantic可降级但要返回 warningProvider-specific只对指定 adapter 有效。例如transparenttrue若是产品承诺应标 required如果只是偏好可 fallback 到后处理抠图但这会改变成本与质量必须写入 plan。三、Capability Registry{model:provider/model-version,operations:[generate,edit],sizes:{mode:aspect_ratio,values:[1:1,16:9,9:16]},supports_seed:false,supports_mask:unknown,output_delivery:inline_binary,inference_data_policy:{gateway_zdr_eligible:unknown,byok_contract_status:unknown},pricing:{type:per_image,amount:PRICE_FROM_VERIFIED_SOURCE,source:MODEL_PAGE_OR_MODELS_API,as_of:QUERY_TIME},registry_version:2026-08-31}示例字段只是网关内部格式具体 capability 必须从官方模型文档确认。unknown与false要分开未知不能被自动当成不支持或支持。Vercel 在 2026 年 4 月新增团队级与请求级 ZDR可用zeroDataRetention: true让 Gateway 只选择符合要求的 provider并在响应 metadata 中留下过滤轨迹这意味着应用不必继续手写每个系统凭证 route 的 ZDR 表。但 ZDR 仍不能被压成模型布尔值。团队/请求策略、Gateway 当前 provider 资格、BYOK 合同和应用自己的 Artifact 保留策略是不同层。特别是 BYOK 协议由用户持有Gateway 无法自动替你证明其保留条款。Capability Registry 应记录可验证的策略输入与执行回执而不是复制一个静态supports_zdrtrue。路由步骤校验请求根据 required capabilities 过滤根据 inference data policy、Gateway 执行回执、BYOK 合同、区域和供应商 allowlist 过滤估算成本与延迟按质量/成本/可用性排序生成参数映射计划返回 warnings创建 Attempt 并发送。四、参数映射不能静默CanonicalProvider AProvider B处理aspectRatio16:9aspect_ratiosize1536x864可映射记录实际尺寸seed42支持不支持strict 时拒绝非 strict 警告count4单次最多 1单次最多 4A 拆 4 次 AttemptformatwebpPNG onlyWebPA 生成后转码新 Artifacteditmask支持不支持不能 fallback 到 BAI SDK 文档指出n可能被自动拆成多次请求maxImagesPerCall还能改变拆分方式正说明“一个 SDK 调用”与“一个供应商请求”不同。成本和幂等必须按 Attempt 记录并固定 SDK 与 adapter 版本否则升级依赖也可能改变 Attempt 数量。五、幂等分三层Business Idempotency用户重复点击或客户端重试不应创建第二个 Jobtenant operation user_request_id → image_job_idAttempt Idempotency若供应商支持原生 idempotency key使用image_job_id attempt_index。若不支持网关只能避免自己重复发送无法保证网络未知状态下供应商没有执行。Artifact Deduplication对返回二进制计算内容哈希避免同一响应被多次保存但不同生成结果即使 prompt 相同也不应按请求哈希去重因为随机性是产品行为。六、重试状态机CREATED → SENT → ACKNOWLEDGED → SUCCEEDED → ARTIFACT_STORED失败可分PRE_SEND_FAILURE确定未到供应商可安全重试REJECTED参数/政策错误不应原样重试PROVIDER_FAILED供应商明确失败按策略 fallbackUNKNOWN_AFTER_SEND已发送但无结果可能计费和生成RESPONSE_RECEIVED_STORE_FAILED已有图片不应重新生成应重试存储。UNKNOWN_AFTER_SEND是关键。自动重试前应查询供应商状态若有、等待宽限期、检查 provider request ID、核对成本预算并在产品允许时要求用户确认。这里还要区分三类“超时”客户端abortSignal、SDK 自身重试策略以及 Gateway/provider timeout。Vercel 当前 provider timeout 文档针对 BYOK并以“开始响应前”的时限触发 failover官方同时提醒部分 provider 不支持取消超时请求仍可能计费。该文档的示例是流式文本不能直接证明图像 provider 具有相同取消语义但它足以证明一个通用边界停止等待不等于远端没有执行。图像网关必须把 timeout 后状态标记为未知除非 provider 给出确定终态。七、Fallback 合同Vercel AI Gateway 已支持模型级 fallback并会按models数组依次尝试。官方 Changelog 进一步说明unsupported input、context limit 和 provider outage 等错误都可能触发 fallback。对文本可用的“先成功者返回”策略放到图像任务上仍需应用层收紧编辑能力、参考图数量、尺寸、透明背景、合规策略和结果许可不一致时技术成功不等于产品兼容。因此 Fallback 计划应在发送前生成{primary:model-a,fallbacks:[{model:model-b,allowed_on:[provider_unavailable,rate_limited],not_allowed_on:[safety_rejection,invalid_prompt],degradations:[seed_not_supported,max_resolution_lower],requires_user_consent:false}]}安全拒绝不能自动换模型绕过。ZDR、训练限制或 BYOK 合同不满足时也不能只因可用性进入 fallback。编辑任务、参考图和人脸一致性通常需要更严格的模型绑定。若使用 Gateway 原生modelsfallback应用应只把已经通过同一 Required Capability Contract 的模型放进数组并从 provider metadata 回收实际 Attempt 链否则应关闭自动模型 fallback由自有状态机逐次发送。八、核心数据表image_jobsid、tenant、request hash、statuscanonical requestrequested countbudget、artifact retention policy、inference data policyfinal artifact IDscreated/finished/cancelled。provider_attemptsjob ID、attempt indexprovider/model、credential typemapped requestSDK/adapter version、provider request IDstatus/errorstarted/endedreported cost/estimated costretry/fallback reason、Gateway routing metadata。artifactssource attempt、parent artifactstorage URI内部引用不给永久公开 URLSHA-256、MIME、尺寸、字节kindraw/thumbnail/moderated/deliveredartifact retention/deletion state。moderation_resultsinput/outputpolicy/model versionlabels/scoresdecisionhuman review。cost_ledgerattempt、charge type、amount、currencyestimated/reported/reconciledprovider invoice referencetenant/user/product attribution。九、取消的真实含义用户点击取消后如果尚未发送终止且不计生成成本已发送但供应商不可取消只能标记cancel_requested结果到达后删除或不交付已生成并计费取消不一定退款派生存储和审核任务仍需停止所有状态必须对用户透明。不要把 UI 的“取消”写成“供应商已停止执行”除非有确认。十、可观测性每个 Job 至少监控queue delayprovider latencyartifact storage latencymoderation latencydelivery latencyattempts/jobunknown-after-send rateduplicate artifact ratecost/requested image 与 cost/delivered imagefallback ratepolicy rejectiondeletion SLA。“每张交付图片成本”比“API 单价”更接近业务现实。风险与限制网关能力目录会过期供应商可能改变默认参数、ZDR 资格和审核政策。参数映射可能看似成功却产生质量退化。自建网关增加运维、合规和账单对账成本。统一抽象应保持可逃生保存原始 provider metadata 和 adapter 版本允许关键模型走原生路径。本文没有运行真实图像请求也没有验证某个 provider 对 abort、timeout、幂等键或查询任务状态的具体支持。UNKNOWN_AFTER_SEND是保守的应用状态设计不是对任一供应商内部实现的断言。结论图像网关的正确抽象不是一个万能generate()而是 Job、Attempt 和 Artifact 的分层状态机。共同语义可以统一特殊能力必须显式SDK 拆分、重试和 Gateway fallback 都要展开成 Attempttimeout 后必须认识未知执行状态成本按 Attempt 对账。做到这些统一入口才不会把供应商差异变成隐形故障。参考资料AI SDK Core: generateImageVercel AI SDK持续更新官方 API 参考一手来源访问日期2026-08-31。AI SDK Core: Image GenerationVercel AI SDK持续更新官方使用文档一手来源访问日期2026-08-31。AI Gateway Image Generation QuickstartVercel2026-03-12 更新官方文档一手来源访问日期2026-08-31。AI Gateway Model FallbacksVercel2026-01-30 更新官方文档一手来源访问日期2026-08-31。Model fallbacks now availableVercel2025-11-10官方 Changelog一手来源访问日期2026-08-31。AI Gateway Provider TimeoutsVercel2026-03-04 更新官方文档一手来源访问日期2026-08-31。Team-wide Zero Data Retention and prompt training controlsVercel2026-04-06官方 Changelog一手来源访问日期2026-08-31。Bring Your Own Key (BYOK)Vercel2026-01-21 更新官方文档一手来源访问日期2026-08-31。