Skip to main content
AIBase 开放平台的统一任务提交入口(POST /v1/openapi/tasks)支持 SYNC(同步)ASYNC(异步) 两种执行模式。不同业务 API 因计算复杂度、大模型调用链路耗时的差异,分别采用对应的执行模式。

SYNC · 同步模式

提交即返回结果。适用于轻量、单步或毫秒级完成的高频服务(如“AI 对话问题挖掘”)。

ASYNC · 异步模式

提交返回任务 ID,异步轮询。适用于涉及多家大模型多轮交互、深度分析的任务(如“GEO 排名”、“品牌得分”等)。

两种模式对比


统一路由与执行流程

无论调用何种业务,客户端始终发起相同的统一入口请求,服务端根据请求体中的 apiCode 自动判断并调度执行模式:

ASYNC 异步模式接入步骤

第一步:提交异步任务

向统一入口发起 POST 请求:
接口接收后立即创建后台任务并返回:

第二步:轮询查询任务状态

拿到 taskId 后,调用通用的异步任务查询接口:
响应示例(成功完成状态):

任务状态枚举说明

任务查询返回的 data.statusInteger 类型,定义如下:
推荐轮询频率: 建议轮询间隔为 10 秒,避免过高频率请求造成网络与限流压力。任务最大轮询时长可根据业务设置(通常建议 120 ~ 300 秒超时上限)。

多语言异步轮询示例


最佳实践与注意事项

  1. 切勿在第一步尝试读取结果:异步模式在提交端点中仅返回 requestIdtaskId,绝不可假设 data.result 在提交接口中存在。
  2. 保持 10 秒合理轮询间隔:过于频繁的轮询(如 1 秒一次)不仅无法加快大模型计算,还会消耗 API 限流配额或引发 HTTP 429 报错。
  3. 设置合理的超时上限:建议客户端为轮询流程设置 3 ~ 5 分钟的兜底超时控制,防止因网络单点中断导致进程永久阻塞。
  4. 日志追踪双标识:排查异步流程时,请在日志中同时保存首次提交的 requestId 和生成的 taskId