Agent 搜索与 AI 问答

POST https://api.serphubapi.com/v1/ai-search

一个接口、答案优先，服务两类来源：

• Agent 搜索 API——deepseek、yuanbao、tavily、exa：专为 Agent 设计的搜索。返回带引用的结果，DeepSeek 和 Tavily 还附简短综合答案。
• AI 问答——chatgpt（Perplexity、Gemini 即将上线）：AI 助手实际给出的回答及其引用来源，实时采集。

用 provider 指定来源，或保持 auto，由 SerpHubAPI 从便宜到贵依次尝试，某个失败就自动换下一个。每次最多扣一次费，全部失败不扣费。

请求参数

参数	类型	默认值	说明
q	string	—	必填。 问题或搜索词（1–2048 个字符）。
provider	string	auto	Agent 搜索 API（deepseek、yuanbao、exa、tavily）或 AI 问答来源（chatgpt）。auto 按价格从低到高依次尝试可用来源。实时列表见 GET /v1/services（category 为 agent 和 ai）。
num	integer	10	引用来源的最大条数，1–100；各来源有各自的上限。
mode	string	live	live 每次都向来源查询；cache_first 允许返回一小时内的缓存答案，半价，命中缓存免费。

curl https://api.serphubapi.com/v1/ai-search \
  -H "X-API-Key: shapi_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"q": "欧盟 AI 法案最新指引有哪些变化？", "provider": "auto"}'

返回结果（200）

快速来源（deepseek、yuanbao、exa、tavily）在同一个请求里直接返回：

{
  "meta": {
    "id": "sch_01J9Z3KQ8W",
    "status": "success",
    "provider": "deepseek",
    "cached": false,
    "credits_charged": 5,
    "time_ms": 2410
  },
  "params": { "q": "欧盟 AI 法案最新指引有哪些变化？", "provider": "auto", "num": 10, "mode": "live" },
  "answer": "欧盟委员会最新的指引明确了……",
  "citations": [
    { "position": 1, "title": "Guidelines on the AI Act", "link": "https://example.eu/ai-act", "snippet": "...", "source": "example.eu", "date": "2026-10-30" }
  ]
}

字段	类型	说明
meta.provider	string	实际作答的来源。provider=auto 时可据此得知用了哪个。
meta.credits_charged	integer	实际扣除的积分：该来源的目录价；cache_first 半价；命中缓存或空结果为 0。
answer	string | null	写好的答案。来源只返回引用、不写答案时为 null（元宝和 Exa 不写答案）。
citations	array	答案依据的来源：position、title、link，有时还有 snippet、source、date、score。

auto 只在来源彻底失败时才换下一个。来源返回了引用但没有答案，也算有结果，auto 会停在这里。

异步任务（202）

有些来源要从聊天界面实时采集答案——目前是 ChatGPT，Perplexity 和 Gemini 上线后也一样。采集通常需要 1–2 分钟，有时更久，一次 HTTP 请求等不了这么久。这类来源会返回 202 Accepted 和一个任务：

{
  "job_id": "aij_01J9Z3KQ8W",
  "status": "pending",
  "provider": "chatgpt",
  "result_url": "/v1/ai-search/jobs/aij_01J9Z3KQ8W"
}

轮询这个任务直到结束：

GET https://api.serphubapi.com/v1/ai-search/jobs/{job_id}

curl https://api.serphubapi.com/v1/ai-search/jobs/aij_01J9Z3KQ8W \
  -H "X-API-Key: shapi_xxxxxxxx"

status 取值：

status	含义
pending	仍在采集。约 5 秒后再查。此时 answer 为 null，citations 为空。
done	已完成。answer、citations、meta 与上面 200 返回的结构相同。
failed	未能完成，返回体带 error（含 code 和 message）。失败的任务不扣费。

{
  "job_id": "aij_01J9Z3KQ8W",
  "status": "done",
  "provider": "chatgpt",
  "answer": "……",
  "citations": [ { "position": 1, "title": "……", "link": "https://..." } ],
  "meta": { "id": "aij_01J9Z3KQ8W", "status": "done", "provider": "chatgpt", "cached": false, "credits_charged": 10, "time_ms": 96400 }
}

任务的计费与保存：

• 创建任务时预留积分，只结算一次：done 按目录价扣费，failed 全部退回。
• 轮询免费。已结束的任务直接返回保存的结果，不再请求来源，也不再扣费。
• 异步任务每次都实时采集，cache_first 对它没有缓存可命中。
• 任务只能用创建它的同一个 API Key 查询，至少保存 24 小时。

轮询示例（Python）

import time, requests

API = "https://api.serphubapi.com"
H = {"X-API-Key": "shapi_xxxxxxxx"}

r = requests.post(f"{API}/v1/ai-search", headers=H, json={"q": "适合初创公司的 CRM 推荐", "provider": "chatgpt"})
body = r.json()
if r.status_code == 202:
    while body["status"] == "pending":
        time.sleep(5)
        body = requests.get(f"{API}{body['result_url']}", headers=H).json()
print(body.get("answer"), body.get("citations"))

轮询示例（JavaScript）

const API = "https://api.serphubapi.com";
const H = { "X-API-Key": "shapi_xxxxxxxx", "Content-Type": "application/json" };

let r = await fetch(`${API}/v1/ai-search`, { method: "POST", headers: H, body: JSON.stringify({ q: "适合初创公司的 CRM 推荐", provider: "chatgpt" }) });
let body = await r.json();
while (r.status === 202 && body.status === "pending") {
  await new Promise((ok) => setTimeout(ok, 5000));
  body = await (await fetch(`${API}${body.result_url}`, { headers: H })).json();
}
console.log(body.answer, body.citations);

使用 provider=auto 时，快速来源作答就直接返回 200，只有不得不兜底到慢速来源时才转为 202 任务——所以两种情况都要处理。

错误

HTTP	错误码	场景
400	validation_error	缺少 q，或 provider 不是 Agent 搜索或 AI 问答来源
401	invalid_api_key	Key 缺失、无效或已停用
402	insufficient_balance	余额不够该来源的单价
404	not_found	查询的任务不存在，或不是用当前 API Key 创建的
429	rate_limited	触发限流或 Key 的积分限额
502	all_upstreams_failed	没有任何 AI 来源能作答，不扣费
503	engine_unavailable	指定的来源未上线或暂不可用

详见错误码。各来源单价见服务与定价。