Perplexity Async Jobs — Long Research with Webhook Callbacks

简介

Perplexity 的 Async Jobs API 把长时间研究当后台任务跑而不是阻塞请求 —— 适合 sonar-deep-research 这种几分钟的查询（否则会让普通 HTTP 连接超时）。轮询状态 endpoint 或注册 webhook 等完成。适合研究报告、市场分析、多源比较 —— 任何宁愿邮件/通知而不愿阻塞的场景。兼容 REST、Python httpx、JS fetch。装机时间 10 分钟。

提交一个 deep research 任务

import httpx, os

headers = {"Authorization": f"Bearer {os.environ['PPLX_API_KEY']}"}

job = httpx.post(
    "https://api.perplexity.ai/async/chat/completions",
    headers=headers,
    json={
        "request": {
            "model": "sonar-deep-research",
            "messages": [{"role": "user", "content": "2026 语音 AI agent 全景：头部平台、延迟基准、价格、目标用例。1500 字。"}],
            "search_domain_filter": ["livekit.io", "vapi.ai", "retellai.com", "elevenlabs.io", "techcrunch.com", "a16z.com"],
        },
    },
).json()

print(job["id"], job["status"])    # status: "QUEUED"

轮询等完成

import time

while True:
    r = httpx.get(f"https://api.perplexity.ai/async/chat/completions/{job['id']}", headers=headers).json()
    if r["status"] == "COMPLETED":
        print(r["response"]["choices"][0]["message"]["content"])
        print("引用：", r["response"]["citations"])
        break
    elif r["status"] == "FAILED":
        raise RuntimeError(r.get("failed_reason"))
    time.sleep(5)

Webhook 完成（生产首选）

job = httpx.post(
    "https://api.perplexity.ai/async/chat/completions",
    headers=headers,
    json={
        "request": {...},
        "webhook": {"url": "https://your-app.com/perplexity/done", "secret": "shared-signing-secret"},
    },
).json()

# 你 endpoint 收到的 POST：
# { "job_id": "...", "status": "COMPLETED", "response": {...} }
# 用 X-Perplexity-Signature header 验 HMAC-SHA256(body, secret)。

状态生命周期

什么时候用 Async 而不是同步

• 预期 >30 秒的 deep-research 模型 → Async（同步打 60 秒超时）
• 后台批量任务（隔夜报告）→ Async
• 用户点「生成报告」走开 → Async + webhook → 邮件
• 实时聊天 → 同步 sonar / sonar-pro

FAQ

Q: 任务能跑多久？ A: deep-research 最多 30 分钟。大多数 1-5 分钟完成。Webhook 在 >~5 分钟基本必备，除非你能保活轮询 loop —— 大多数平台不可靠。

Q: 任务完成时我 webhook 挂了怎办？ A: Perplexity 按指数退避重试最多约 24 小时。之后结果通过 GET job ID 可取，保留 7 天。做幂等：存 job_id、重试去重。

Q: 能取消在飞的任务吗？ A: 能 —— DELETE job endpoint。用户离开研究请求时有用。不返回部分结果；按已搜的部分计费。