跳到主要内容

开发者说明

执行生命周期

先确认自己真的走正式接口,再拿 Bearer、发第一条请求、处理同步或异步结果。

适合谁已经决定做直接接口接入的开发团队
解决动作理解 Bearer、请求对象和结果处理链路
下一步进入首次请求、接口参考和上线准备
适合场景团队已经决定做直接接口接入
不适合业务方选择接入模式时阅读
步骤 01获取凭证
步骤 02发送请求
步骤 03处理结果

本页说明一次请求从提交到返回结果的处理路径,以及你在集成侧应该如何保存标识、如何处理同步/异步差异。

适合需要把结果处理做稳定的开发团队;如果你还没跑通第一条请求,先看 首次请求快速开始

一句话原则

只沿响应返回的 follow-up URL 继续处理;不要自行拼接 URL。

推荐阅读

一次执行的四个节点

CURRENT PUBLIC PATH

  1. 构造与校验

    使用 text 或 structured_input,随后由平台校验凭证、required_scopes 与可执行请求体。

  2. 当前公开:200 同步完成

    当前预览以同步响应收束;从响应 envelope 读取结果,不推断未公开能力。

  3. 固定保存的回执栏

    把一次真实执行留成可追踪、可排障、可审计的本地证据。

    • request_id
    • trace_id
    • idempotency_key(若使用)
    • usage_applications
    • exact_bridge(可选)

生命周期

  1. 构造输入:使用 text,需要更多上下文时使用 structured_input。中性协议对象也应放入 structured_input,而不是作为默认顶层 HTTP contract。
  2. 提交请求:携带 Bearer 调用 POST /api/execute
  3. 请求校验:校验凭证与 required_scopes,并检查请求体是否满足可执行结构。
  4. 接收结果200 表示同步完成;202 表示已受理并进入异步 workflow(若开放)。
  5. 保存与跟进:同步保存返回结果;异步只使用响应中的 workflow URLs 跟进。

同步与异步处理

200 同步完成

保存 outputusage_applications、可选 exact_bridge,以及 request_idtrace_id。这些字段用于本地展示、排障与审计关联。

202 异步受理

保存 workflow 标识和平台返回的:

  • stream_url
  • query_url
  • cancel_url

后续轮询、流式读取或取消都应调用这些返回地址;不要自行拼接 URL。

提示最容易遗漏的是:把标识保存下来

无论你做同步还是异步,都建议把 request_idtrace_ididempotency_key(若使用)、usage_applications、以及异步的 follow-up URL 一起保存。这样排障、对账与回放才不会断链。

建议保存的关联信息

无论同步还是异步,建议保存:request_idtrace_idusage_applications、可选 exact_bridge,以及异步 workflow 标识与 URLs。这样排障、审计和对账不会断链。

推荐阅读

继续阅读