用户 API 使用文档

本文档说明如何接入问答服务 API。你会收到一个专属 api_key，请把它当作密码保管，不要提交到代码仓库、公开文档、前端页面或聊天记录中。

基本信息

• API 基础地址：https://app.airankone.com/openapi/v1
• 认证方式：每个业务接口都需要携带 api_key
• 健康检查接口：GET /openapi/v1/health 不需要认证
• 请求与响应格式：application/json

示例中的变量：

BASE_URL="https://app.airankone.com/openapi/v1"
API_KEY="<我提供给你的api_key>"

API 细节

具体接口说明、入参、响应结构、分页参数和过滤参数均以 API 参考文档 为准。

认证方式

推荐使用 Authorization: Bearer <api_key>：

curl "$BASE_URL/questions" \
  -H "Authorization: Bearer $API_KEY"

也可以使用 X-API-Key：

curl "$BASE_URL/questions" \
  -H "X-API-Key: $API_KEY"

如果缺少 key，会返回 401；如果 key 无效，会返回 403。

典型调用流程

一次完整问答通常分为四步：

1. 创建问题：POST /openapi/v1/questions
2. 创建任务：POST /openapi/v1/tasks
3. 轮询任务或结果：GET /openapi/v1/tasks、GET /openapi/v1/runs
4. 获取回答与引用来源：GET /openapi/v1/runs/{run_id} 或 GET /openapi/v1/citations

服务会把问题发送到一个或多个已启用的平台。任务创建后是异步执行的，接口不会立即返回最终回答；需要通过任务和结果接口查询执行状态。

创建任务前，先通过 GET /openapi/v1/platforms 查看可用平台，并在创建任务时使用平台 id。

Python 示例

import time
import requests

BASE_URL = "https://app.airankone.com/openapi/v1"
API_KEY = "<我提供给你的api_key>"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

question_resp = requests.post(
    f"{BASE_URL}/questions",
    headers=headers,
    json={"content": "请总结今天新能源汽车行业的主要趋势"},
)
question_resp.raise_for_status()
question = question_resp.json()

platforms_resp = requests.get(
    f"{BASE_URL}/platforms",
    headers=headers,
    params={"enabled": "true"},
)
platforms_resp.raise_for_status()
platform_ids = [item["id"] for item in platforms_resp.json()["items"][:2]]

task_resp = requests.post(
    f"{BASE_URL}/tasks",
    headers=headers,
    json={"question_id": question["id"], "platform_ids": platform_ids},
)
task_resp.raise_for_status()
expected_runs = len(task_resp.json()["tasks"])

while True:
    runs_resp = requests.get(
        f"{BASE_URL}/runs",
        headers=headers,
        params={
            "question_id": question["id"],
            "include_citations": "true",
        },
    )
    runs_resp.raise_for_status()
    runs = runs_resp.json()["items"]

    if len(runs) >= expected_runs and all(run["status"] in {"succeeded", "failed"} for run in runs):
        break

    time.sleep(5)

for run in runs:
    print(run["platform_name"], run["status"])
    print(run["answer"])

常见错误

HTTP 状态码	含义	处理方式
400	请求参数不合法，例如平台 ID 不存在或已禁用	检查请求体和平台 ID
401	没有提供 API key	添加 Authorization 或 X-API-Key 请求头
403	API key 无效	确认 key 是否复制完整，或联系管理员重新生成
404	资源不存在，或不属于当前 key 对应的命名空间	确认 ID 是否正确
500	服务内部错误	稍后重试，仍失败则联系管理员

安全建议

• 不要把 api_key 写在前端代码里。
• 不要把 api_key 提交到 Git、日志、截图或公开文档中。
• 后端调用时建议通过环境变量读取 api_key。
• 如果怀疑 api_key 泄露，请立即联系管理员更换。