本页说明一次请求从提交到返回结果的处理路径,以及你在集成侧应该如何保存标识、如何处理同步/异步差异。
适合需要把结果处理做稳定的开发团队;如果你还没跑通第一条请求,先看 首次请求 与 快速开始。
一句话原则
只沿响应返回的 follow-up URL 继续处理;不要自行拼接 URL。
推荐阅读
一次执行的四个节点
CURRENT PUBLIC PATH
构造与校验
使用 text 或 structured_input,随后由平台校验凭证、required_scopes 与可执行请求体。
当前公开:200 同步完成
当前预览以同步响应收束;从响应 envelope 读取结果,不推断未公开能力。
固定保存的回执栏
把一次真实执行留成可追踪、可排障、可审计的本地证据。
- request_id
- trace_id
- idempotency_key(若使用)
- usage_applications
- exact_bridge(可选)
生命周期
- 构造输入:使用
text,需要更多上下文时使用structured_input。中性协议对象也应放入structured_input,而不是作为默认顶层 HTTP contract。 - 提交请求:携带 Bearer 调用
POST /api/execute。 - 请求校验:校验凭证与
required_scopes,并检查请求体是否满足可执行结构。 - 接收结果:
200表示同步完成;202表示已受理并进入异步 workflow(若开放)。 - 保存与跟进:同步保存返回结果;异步只使用响应中的 workflow URLs 跟进。
同步与异步处理
200 同步完成
保存 output、usage_applications、可选 exact_bridge,以及 request_id、trace_id。这些字段用于本地展示、排障与审计关联。
202 异步受理
保存 workflow 标识和平台返回的:
stream_urlquery_urlcancel_url
后续轮询、流式读取或取消都应调用这些返回地址;不要自行拼接 URL。
提示最容易遗漏的是:把标识保存下来
无论你做同步还是异步,都建议把 request_id、trace_id、idempotency_key(若使用)、usage_applications、以及异步的 follow-up URL 一起保存。这样排障、对账与回放才不会断链。
建议保存的关联信息
无论同步还是异步,建议保存:request_id、trace_id、usage_applications、可选 exact_bridge,以及异步 workflow 标识与 URLs。这样排障、审计和对账不会断链。
推荐阅读