异步任务与文件
异步任务
耗时较长的工具(多见于生成视频、生成图片)会自动转成异步执行:执行接口不直接返回结果,而是先返回一个任务号。
{
"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 小时内取走、保存好。 - 结果里的图片、视频等通常是文件链接,需要长期保存的话请及时下载。
文件上传
需要传入文件(图片、音频、文档等)的工具,支持哪种方式以该工具的参数说明为准,常见两种:
方式一:先上传,再传地址
调用免费工具
ae_file_service_get_upload_addr获取上传地址,参数:参数 说明 ext文件扩展名,不含点,只允许字母和数字,如 pngsize_bytes文件大小(字节),最大 524,288,000(500 MiB) ttl_minutes上传地址的有效期(分钟),最大 43,200(30 天) 返回
uploadURL(上传地址)和downloadURL(文件地址)。用 PUT 请求把文件内容上传到
uploadURL:curl --request PUT --upload-file ./photo.png "<uploadURL>"把
downloadURL作为参数传给目标工具。
downloadURL 拿到链接的人都能访问,不要用这种方式上传敏感文件。
方式二:直接传 base64
部分工具支持把文件 base64 编码后直接作为参数传入。适合小文件;文件较大时优先用方式一。
