受控开放

Base URL 与白名单端点可验证；API Key 与生产权限仍通过开通流程发放。本文档用于集成预览，不等价于匿名自助开放。

当前公开集成以“请求 → 响应”为主：你发起 POST /api/execute，按响应返回的结构处理结果。

推荐阅读

当前可采用的结果处理方式

同步响应

当前公开预览优先从 200 响应开始。

Follow-up URL

异步开放时沿响应中的地址继续查询或读取。

Webhook 准备

提前准备验签、重试、幂等、落库与告警。

这意味着：

• 不要默认“平台一定会回调你的 webhook”
• 异步能力（若开放）会以“响应返回 follow-up URL”的方式优先成立
• webhook（若未来开放）会以平台正式契约发布，并包含验签、重试与幂等规则

提示异步优先使用 follow-up URL

当 execution_mode="async"（在未来开放的前提下），更稳的模式是：平台返回 202，并在响应里给出 stream_url / query_url / cancel_url。集成方沿这些 URL 继续读取，不需要等待回调。

当前建议怎么做

1. 先把同步链路做稳：只处理 execution_mode="sync" 的 200 响应。
2. 需要异步时，按 执行生命周期 的方式接住响应中的 follow-up URL（而不是自行拼接 URL）。
3. 真正需要 webhook 的团队，先把“验签、重试、幂等、落库与告警”准备好，再等待正式开放契约。

推荐阅读

继续阅读

把异步、错误处理与上线准备一起看，能避免后续返工。

执行生命周期

同步/异步差异与 follow-up URL 的处理方式。

Error Model

三段式错误分类，写出可维护的重试策略。

生产准备

幂等、日志、告警与安全检查。

API Reference

字段与响应结构对照。