公开 API 的交互式文档。
X-GenStudio-Signature 头里**可能有多个** v1 值。secret 轮换的 24 小时宽限期内会有两个 —— 一个用新 secret 签、一个用旧的。请**逐一尝试、任一命中即通过**。只读取单个 v1 的实现会在整个轮换期拒掉每一封投递。
请拒绝 t 与当前时间相差超过 5 分钟的请求。签名的内容是 "{t}.{rawBody}" —— 时间戳在签名之内，改了它签名就对不上。
X-GenStudio-Signature: t=1785000000,v1=<hex>,v1=<hex>
X-GenStudio-Event: generation.succeeded
X-GenStudio-Delivery: <delivery id>
X-GenStudio-Event-Version: 1POST /api/v1/me/webhook-endpoints/{id}/rotate-secret 会**一次性**返回新 secret。旧 secret 在宽限期内继续有效，好让你从容部署而不丢投递；具体时长在响应里给出。
**宽限期内轮换第二次会让最早那把 secret 立刻失效。**endpoint 只保留一把旧 secret，第二次轮换会把它覆盖掉。请等一次轮换部署完成之后再开始下一次。
webhook URL 必须是 https 且端口为 443。若你自托管在别的端口，请在 443 上用反向代理终结 TLS，或使用 ngrok / Cloudflare Tunnel 这类隧道 —— 两者本就在 443 终结，本地联调无需改动。
轮换 secret 与重新发起归属验证**仅在站内可用**。两者都要求重新输入密码，而 API Key 持有者没有密码上下文。这是 MVP 的一次有意的范围划定，不是端点遗漏。
同一个事件最多投递 9 次，**至少**横跨 31 小时。请照这个跨度设你的去重窗口：同一个 X-GenStudio-Delivery id 在这段时间里可能到达多次。
按 X-GenStudio-Delivery 去重，不要按报文去重。同一事件的每一次重试共用同一个 delivery id，而签名**不同**（每次重试都用新的时间戳重新签）。
回任意 2xx 即算确认。其余情况——**包括响应体回得太慢**——都算这一次投递失败并会重试。用完次数之后这一封被判死，你可以从送达日志里手动重投。
anon_trial_unavailable — 503 — 匿名试用暂不可用，请稍后再试，或注册一个完整账号。asset_lost — 410 — 该文件已不可用，积分已退回。download_timeout — 504 — 产物获取超时，积分已退回。endpoint_not_verified — 409 — 该 webhook 地址尚未完成验证。forbidden — 403 — 你的账号已登录，但没有执行此操作的权限。idempotency_key_reuse — 422 — 该幂等键已被使用，且本次请求内容与首次提交不一致。insufficient_credits — 402 — 需要 {required} 积分，当前只有 {available}。insufficient_credits_on_fallback — 402 — 备选模型需要 {required} 积分，当前只有 {available}。积分已退回。internal_error — 500 — 发生意外的内部错误。invalid_credentials — 401 — 登录失败。检查邮箱与密码，并确认邮箱已完成验证。invalid_params — 422 — 部分参数不合法。invalid_state — 422 — 当前状态不允许执行该操作。invite_invalid — 422 — 这个邀请码用不了，向邀请你的人再要一个。job_stalled — 500 — 任务始终未开始，积分已退回。job_stuck — 500 — 任务停止推进，积分已退回。maintenance — 503 — 因计划内维护，暂时不接受新的生成任务。已在进行的任务会照常跑完，历史记录也照常可看。请稍后再试。not_found — 404 — 请求的资源不存在或对你不可见。provider_auth_failed — 500 — 服务配置有误，暂时无法连接供应商，积分已退回；请联系 support@yaspost.com。rate_limited — 429 — 尝试次数过多，稍后再试。reauth_required — 401 — 请重新输入密码以继续。submit_unknown — 500 — 无法确认该任务是否已提交，积分已退回。subscription_required — 403 — 该能力仅向订阅用户开放。升级订阅后即可使用。unauthorized — 401 — 登录状态已失效，请重新登录。upload_too_large — 413 — 文件超过 {maxBytes} 字节的上限。upstream_error — 502 — 供应商返回错误，积分已退回。upstream_rate_limited — 502 — 供应商繁忙，请稍后重试，积分已退回。upstream_rejected — 502 — 供应商拒绝了此次生成，积分已退回。upstream_timeout — 504 — 供应商处理超时，积分已退回。upstream_unavailable — 502 — 供应商暂时不可用，请稍后重试，积分已退回。verification_failed — 422 — 验证码不对，重新获取一个。