POST /v1/openapi/tasks)支持 SYNC(同步) 和 ASYNC(异步) 两种执行模式。不同业务 API 因计算复杂度、大模型调用链路耗时的差异,分别采用对应的执行模式。
SYNC · 同步模式
提交即返回结果。适用于轻量、单步或毫秒级完成的高频服务(如“AI 对话问题挖掘”)。
ASYNC · 异步模式
提交返回任务 ID,异步轮询。适用于涉及多家大模型多轮交互、深度分析的任务(如“GEO 排名”、“品牌得分”等)。
两种模式对比
| 维度 | SYNC · 同步执行 | ASYNC · 异步执行 |
|---|---|---|
| 典型接口 | geo.questions_corr_recommend(AI 对话问题挖掘) | geo.ranking、geo.rank_monitor、geo.brand、geo.checker |
| 执行耗时 | 毫秒级至秒级 | 数秒至数十秒(取决于并发大模型数量与响应) |
| 提交接口返回 | 直接返回业务 data.result | 返回 data.taskId 与 data.requestId |
| 调用方后续动作 | 直接解析业务结果,结束调用 | 间隔 10 秒调用任务查询接口,直至终态 |
| 结果获取端点 | POST /v1/openapi/tasks | GET /v1/openapi/tasks/{taskId} |
统一路由与执行流程
无论调用何种业务,客户端始终发起相同的统一入口请求,服务端根据请求体中的apiCode 自动判断并调度执行模式:
ASYNC 异步模式接入步骤
第一步:提交异步任务
向统一入口发起POST 请求:
POST https://api.aibase.cn/v1/openapi/tasks
AIBase-API-Key: AIBase_xxxxxxxxxxxxxxxx
Content-Type: application/json
{
"apiCode": "geo.ranking",
"data": {
"keyword": "性价比高的智能手机推荐",
"brandKeyword": ["小米", "华为"],
"platforms": ["deepseek", "baidu"]
}
}
{
"code": 200,
"msg": "成功",
"data": {
"requestId": "599b2f8f39078d",
"taskId": "task_d77143abc87642d4842ff588197faa89"
},
"timeStamp": 1789550182642
}
第二步:轮询查询任务状态
拿到taskId 后,调用通用的异步任务查询接口:
GET https://api.aibase.cn/v1/openapi/tasks/task_d77143abc87642d4842ff588197faa89
AIBase-API-Key: AIBase_xxxxxxxxxxxxxxxx
{
"code": 200,
"msg": "成功",
"data": {
"taskId": "task_d77143abc87642d4842ff588197faa89",
"status": 2,
"statusDesc": "成功",
"result": {
"keyword": "性价比高的智能手机推荐",
"data": []
}
},
"timeStamp": 1789551724519
}
任务状态枚举说明
任务查询返回的data.status 为 Integer 类型,定义如下:
| status | 标识 | 说明 | 开发者动作 |
|---|---|---|---|
1 | PENDING | 任务排队或执行中 | 等待 10 秒后继续下一次查询 |
2 | SUCCESS | 任务执行成功 | 停止轮询,从 data.result 读取业务结果 |
3 | FAILED | 任务执行失败 | 停止轮询,记录日志或进入降级逻辑 |
4 | TIMEOUT | 任务执行超时 | 停止轮询,提示超时或适度重试 |
5 | CANCELLED | 任务已被取消 | 停止轮询 |
推荐轮询频率: 建议轮询间隔为 10 秒,避免过高频率请求造成网络与限流压力。任务最大轮询时长可根据业务设置(通常建议 120 ~ 300 秒超时上限)。
多语言异步轮询示例
- Python
- Node.js
- Java
- cURL
import os
import time
import requests
API_KEY = os.environ.get("AIBASE_API_KEY", "AIBase_xxxxxxxxxxxxxxxx")
HEADERS = {
"AIBase-API-Key": API_KEY,
"Content-Type": "application/json"
}
# 1. 提交异步任务
submit_resp = requests.post(
"https://api.aibase.cn/v1/openapi/tasks",
headers=HEADERS,
json={
"apiCode": "geo.ranking",
"data": {
"keyword": "性价比高的智能手机推荐",
"brandKeyword": ["小米", "华为"],
"platforms": ["deepseek", "baidu"]
}
},
timeout=30
)
submit_data = submit_resp.json()
if submit_data.get("code") != 200:
raise RuntimeError(f"任务提交失败: {submit_data}")
task_id = submit_data["data"]["taskId"]
print(f"任务已提交,taskId: {task_id}")
# 2. 轮询任务状态(间隔 10 秒)
max_retries = 30 # 最多轮询 30 次(约 5 分钟)
for i in range(max_retries):
time.sleep(10)
query_resp = requests.get(
f"https://api.aibase.cn/v1/openapi/tasks/{task_id}",
headers=HEADERS,
timeout=30
)
query_data = query_resp.json()
status = query_data.get("data", {}).get("status")
if status == 2: # SUCCESS
print("任务成功完成!")
result = query_data["data"]["result"]
print("业务结果:", result)
break
elif status == 1: # PENDING
print(f"[{i+1}/{max_retries}] 任务仍在执行中,等待下一次查询...")
else: # 3 FAILED, 4 TIMEOUT, 5 CANCELLED
desc = query_data.get("data", {}).get("statusDesc", "未知状态")
raise RuntimeError(f"任务异常终止,状态: {status} ({desc})")
import { setTimeout } from "node:timers/promises";
const apiKey = process.env.AIBASE_API_KEY || "AIBase_xxxxxxxxxxxxxxxx";
const headers = {
"AIBase-API-Key": apiKey,
"Content-Type": "application/json",
};
// 1. 提交异步任务
const submitRes = await fetch("https://api.aibase.cn/v1/openapi/tasks", {
method: "POST",
headers,
body: JSON.stringify({
apiCode: "geo.ranking",
data: {
keyword: "性价比高的智能手机推荐",
brandKeyword: ["小米", "华为"],
platforms: ["deepseek", "baidu"],
},
}),
});
const submitData = await submitRes.json();
if (submitData.code !== 200) {
throw new Error(`提交失败: ${JSON.stringify(submitData)}`);
}
const taskId = submitData.data.taskId;
console.log("任务已创建,taskId:", taskId);
// 2. 轮询状态(间隔 10 秒)
const maxRetries = 30;
for (let i = 0; i < maxRetries; i++) {
await setTimeout(10000);
const queryRes = await fetch(`https://api.aibase.cn/v1/openapi/tasks/${taskId}`, {
headers,
});
const queryData = await queryRes.json();
const status = queryData.data?.status;
if (status === 2) {
console.log("任务成功!结果:", queryData.data.result);
break;
} else if (status === 1) {
console.log(`[${i + 1}/${maxRetries}] 任务处理中,继续等待...`);
} else {
throw new Error(`任务失败或终止,status: ${status}`);
}
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
public class AIBaseAsyncDemo {
public static void main(String[] args) throws Exception {
String apiKey = System.getenv().getOrDefault("AIBASE_API_KEY", "AIBase_xxxxxxxxxxxxxxxx");
HttpClient client = HttpClient.newHttpClient();
// 1. 提交任务
String submitJson = """
{
"apiCode": "geo.ranking",
"data": {
"keyword": "性价比高的智能手机推荐",
"brandKeyword": ["小米", "华为"],
"platforms": ["deepseek", "baidu"]
}
}
""";
HttpRequest submitReq = HttpRequest.newBuilder()
.uri(URI.create("https://api.aibase.cn/v1/openapi/tasks"))
.header("AIBase-API-Key", apiKey)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(submitJson))
.build();
HttpResponse<String> submitResp = client.send(submitReq, HttpResponse.BodyHandlers.ofString());
// 需引入 JSON 库解析返回的 taskId,此处以变量伪代码示意
String taskId = "task_d77143abc87642d4842ff588197faa89";
// 2. 轮询查询(间隔 10 秒)
for (int i = 0; i < 30; i++) {
Thread.sleep(10000);
HttpRequest queryReq = HttpRequest.newBuilder()
.uri(URI.create("https://api.aibase.cn/v1/openapi/tasks/" + taskId))
.header("AIBase-API-Key", apiKey)
.GET()
.build();
HttpResponse<String> queryResp = client.send(queryReq, HttpResponse.BodyHandlers.ofString());
// 判断返回体中的 status:
// status == 2 -> 获取 data.result,跳出循环
// status == 1 -> 继续等待
// status >= 3 -> 异常终止
}
}
}
# 1. 提交任务获取 taskId
curl --location 'https://api.aibase.cn/v1/openapi/tasks' \
--header 'AIBase-API-Key: AIBase_xxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
"apiCode": "geo.ranking",
"data": {
"keyword": "性价比高的智能手机推荐",
"brandKeyword": ["小米", "华为"],
"platforms": ["deepseek", "baidu"]
}
}'
# 2. 间隔 10 秒轮询查询
curl --location 'https://api.aibase.cn/v1/openapi/tasks/task_d77143abc87642d4842ff588197faa89' \
--header 'AIBase-API-Key: AIBase_xxxxxxxxxxxxxxxx'
最佳实践与注意事项
- 切勿在第一步尝试读取结果:异步模式在提交端点中仅返回
requestId和taskId,绝不可假设data.result在提交接口中存在。 - 保持 10 秒合理轮询间隔:过于频繁的轮询(如 1 秒一次)不仅无法加快大模型计算,还会消耗 API 限流配额或引发 HTTP 429 报错。
- 设置合理的超时上限:建议客户端为轮询流程设置 3 ~ 5 分钟的兜底超时控制,防止因网络单点中断导致进程永久阻塞。
- 日志追踪双标识:排查异步流程时,请在日志中同时保存首次提交的
requestId和生成的taskId。