异步任务与文件

异步任务

耗时较长的工具(多见于生成视频、生成图片)会自动转成异步执行:执行接口不直接返回结果,而是先返回一个任务号。

{
  "task_id": "…",
  "status": "created",
  "query_tool": "ae_get_result",
  "description": "task accepted; poll the result via query_tool with this task_id"
}

取结果

用工具 ae_get_result 查询,参数是任务号:

curl --request POST \
  --url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_get_result' \
  --header "X-Api-Key: $AGENTEARTH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{"params":{"task_id":"<任务号>"}}'
  • 任务还没完成:返回进行中的状态,隔一会儿再查。
  • 任务完成:返回原工具的执行结果,格式和同步执行一样。
  • ae_get_result 不收费,也不计入限流,可以放心轮询。

MCP 下用 ExecuteTool 调用 ae_get_result,CLI 下用 ae execute,参数相同。

注意事项

  • 不要重复提交。 拿到任务号后只轮询结果,不要重新执行原工具:每次执行都会创建新任务、重新扣费。
  • 任务保留 24 小时。 超过 24 小时,或任务号不存在,统一返回 {"status": "not_found"}。结果请在 24 小时内取走、保存好。
  • 结果里的图片、视频等通常是文件链接,需要长期保存的话请及时下载。

文件上传

需要传入文件(图片、音频、文档等)的工具,支持哪种方式以该工具的参数说明为准,常见两种:

方式一:先上传,再传地址

  1. 调用免费工具 ae_file_service_get_upload_addr 获取上传地址,参数:

    参数 说明
    ext 文件扩展名,不含点,只允许字母和数字,如 png
    size_bytes 文件大小(字节),最大 524,288,000(500 MiB)
    ttl_minutes 上传地址的有效期(分钟),最大 43,200(30 天)

    返回 uploadURL(上传地址)和 downloadURL(文件地址)。

  2. 用 PUT 请求把文件内容上传到 uploadURL:

    curl --request PUT --upload-file ./photo.png "<uploadURL>"
  3. 把 downloadURL 作为参数传给目标工具。

downloadURL 拿到链接的人都能访问,不要用这种方式上传敏感文件。

方式二:直接传 base64

部分工具支持把文件 base64 编码后直接作为参数传入。适合小文件;文件较大时优先用方式一。