爱口扫 AI 开放平台

Overview

概览

平台把厂商 AI 能力封装为统一 API。客户端只需要对接患者、扫描、任务、报告四类资源，不接触厂商地址、凭证或品牌。

01

提交扫描

8 张影像 + 患者

02

排队调度

按租户公平排队

03

AI 分析

3–5 并发槽位

04

报告渲染

品牌化 PDF

05

通知/下载

Webhook + 签名 URL

异步任务

提交即返回 202，排队、分析、渲染、完成状态可查，适合 3–5 并发的厂商限制。

多租户隔离

API Key 绑定租户，配额、限流、数据、审计全部隔离。

完全去品牌

简易/详细报告都在平台本地渲染，机构信息、页眉页脚、报告模板可配置。

报告允许延迟交付。平台会把扫描放入队列，按医生账号的 3–5 个 AI 槽位依次分析。客户通过 Job 状态或 Webhook 获取报告，不需要保持长连接。

Quickstart

快速开始

五步完成一次完整扫描：创建患者 → 提交 8 张影像 → 查询任务 → 下载报告。

1. 获取 API Key

在控制台创建 API Key，并保存到服务端环境变量。Key 只显示一次，不要放进浏览器或移动端。

API Key 仅限服务端使用。前端/APP 应调用你自己的业务后端，由后端再调用本平台。

2. 创建患者

# POST /v1/patients
curl -X POST "https://api.aikousao.com/v1/patients" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "张三",
    "gender": "male",
    "birthdate": "1990-01-01",
    "phone": "13800000000",
    "consent": true,
    "external_id": "clinic-a-0001"
  }'

{
  "patient_id": "pat_8f3k2m",
  "vendor_status": "bound",
  "created_at": "2026-10-29T10:00:00Z"
}

3. 提交扫描

一次提交 8 张影像。`types` 与 `files` 按顺序一一对应；支持 JPEG/PNG，单张不超过 10 MB。

curl -X POST "https://api.aikousao.com/v1/scans" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: scan-20261029-0001" \
  -F "patient_id=pat_8f3k2m" \
  -F "files=@closed_left.jpg"  -F "types=closed_left" \
  -F "files=@closed_center.jpg" -F "types=closed_center" \
  -F "files=@closed_right.jpg" -F "types=closed_right" \
  -F "files=@open_left.jpg"   -F "types=open_left" \
  -F "files=@open_center.jpg" -F "types=open_center" \
  -F "files=@open_right.jpg"  -F "types=open_right" \
  -F "files=@upper.jpg"       -F "types=upper" \
  -F "files=@lower.jpg"       -F "types=lower"

import os, requests

files = [
    ("files", ("closed_left.jpg", open("closed_left.jpg", "rb"), "image/jpeg")),
    ("files", ("closed_center.jpg", open("closed_center.jpg", "rb"), "image/jpeg")),
    # ... 其余 6 张
]
types = [("types", t) for t in [
    "closed_left", "closed_center", "closed_right",
    "open_left", "open_center", "open_right",
    "upper", "lower",
]]

r = requests.post(
    "https://api.aikousao.com/v1/scans",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}",
             "Idempotency-Key": "scan-20261029-0001"},
    data=[("patient_id", "pat_8f3k2m")] + types,
    files=files,
    timeout=60,
)
print(r.status_code, r.json())

4. 查询任务

curl "https://api.aikousao.com/v1/jobs/job_9d2x7q" \
  -H "Authorization: Bearer $API_KEY"

# 202 提交后，每 5–10 秒轮询一次；或配置 Webhook

5. 下载报告

curl "https://api.aikousao.com/v1/reports/rep_7k4m2p/download?type=detailed" \
  -H "Authorization: Bearer $API_KEY"

# 返回签名 URL，直接下载 PDF

Authentication

认证与安全

所有请求使用 Bearer API Key。Key 绑定租户和权限范围，服务端从 Key 解析租户，不接受客户端传入的租户 ID。

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: scan-20261029-0001   # 写接口建议携带

权限范围（Scopes）

Scope	说明
`patient:write`	创建/更新患者
`patient:read`	读取患者信息
`scan:write`	提交扫描、上传影像
`report:read`	查询任务、读取/下载报告
`usage:read`	读取租户用量
`webhook:write`	配置 Webhook

不要把 Key 放进网页、APP 或公开仓库；服务端保存，支持轮换和 IP 白名单。写接口使用 Idempotency-Key 防止重复创建任务。

Async Jobs

异步任务模型

扫描提交后不会同步等待 AI 结果。平台返回 Job ID，由队列按医生账号的 3–5 个并发槽位调度；报告完成后通过 Webhook 或轮询通知。

QUEUED

排队中

等待 AI 槽位

ANALYZING

分析中

AI 正在识别

RENDERING

生成报告

本地渲染 PDF

COMPLETED

已完成

可下载

Job 对象

{
  "job_id": "job_9d2x7q",
  "status": "queued",
  "queue_position": 7,
  "estimated_wait_seconds": 420,
  "report_ids": [],
  "created_at": "2026-10-29T10:00:00Z"
}

状态	含义	客户端动作
queued	已提交，排队等待槽位	展示预计等待时间，继续轮询
analyzing	AI 正在分析	展示进度，继续轮询
rendering	报告生成中	稍候，继续轮询
completed	报告可下载	读取 report_ids / 下载
failed	失败（可重试）	根据 error.code 处理

预计等待时间按队列位置和该账号并发数估算，每 30–60 秒更新。报告允许延迟交付，建议客户端使用 Webhook，减少轮询。

Patients

患者

患者是扫描与报告的主体。平台在本地维护患者与厂商账号的映射，客户端只需使用平台 patient_id。

POST/v1/patients创建患者

字段	类型	必填	说明
`name`	string	是	患者姓名
`gender`	string	是	`male` / `female` / `unknown`
`birthdate`	string	否	`YYYY-MM-DD`
`phone`	string	是	患者手机号，用于厂商建档与去重
`consent`	boolean	是	是否已获得患者影像处理同意
`external_id`	string	否	你方患者编号，便于对账

{
  "patient_id": "pat_8f3k2m",
  "vendor_status": "bound",
  "created_at": "2026-10-29T10:00:00Z"
}

GET/v1/patients/{patient_id}查询患者

返回患者基本信息、绑定状态和最近扫描。手机号默认脱敏返回。

Scans

扫描上传

一次扫描固定 8 张口内影像。平台校验数量、类型和顺序，然后创建异步任务。

POST/v1/scans提交扫描

字段	类型	必填	说明
`patient_id`	string	是	患者 ID
`files`	file[]	是	8 张影像，JPEG/PNG，单张 ≤ 10 MB
`types`	string[]	是	与 files 顺序一致，见下方标准位

标准位

types	含义
`closed_left`	闭合左侧
`closed_center`	闭合正面
`closed_right`	闭合右侧
`open_left`	张口左侧
`open_center`	张口正面
`open_right`	张口右侧
`upper`	上颌
`lower`	下颌

{
  "job_id": "job_9d2x7q",
  "status": "queued",
  "estimated_wait_seconds": 420
}

必须正好 8 张，且 types 不重复；否则返回 422 SCAN_INCOMPLETE。建议携带 Idempotency-Key，避免重试产生重复任务。

Jobs

任务状态

通过 Job ID 查询排队、分析、渲染状态。报告完成后返回 report_ids。

GET/v1/jobs/{job_id}查询任务

字段	说明
`status`	`queued` / `analyzing` / `rendering` / `completed` / `failed`
`queue_position`	当前排队位置（queued 时有效）
`estimated_wait_seconds`	预计等待秒数
`report_ids`	完成的报告 ID 列表
`error`	失败时的 `{code, message}`

{
  "job_id": "job_9d2x7q",
  "status": "analyzing",
  "queue_position": 0,
  "estimated_wait_seconds": 180,
  "report_ids": [],
  "error": null
}

Reports

报告

每次扫描生成两份报告：简易摘要和详细报告。PDF 由平台本地渲染，机构名称、logo、页眉页脚可按租户配置。

简易报告 · simple

1–2 页摘要：等级、主要问题、建议、机构信息、免责声明。适合患者快速查看。

详细报告 · detailed

01 受检者信息、02 AI 分析、03 建议、04 影像照片、05 影像分析（数字标号 + 问题清单）。

GET/v1/reports/{report_id}报告元数据

{
  "report_id": "rep_7k4m2p",
  "job_id": "job_9d2x7q",
  "type": "detailed",
  "grade": "IV",
  "teeth_count": 28,
  "pages": 7,
  "created_at": "2026-10-29T10:05:00Z"
}

GET/v1/reports/{report_id}/download?type=simple|detailed获取下载地址

返回 15–60 分钟有效的签名 URL；客户端直接下载，不需要再带 API Key。

{
  "report_id": "rep_7k4m2p",
  "type": "detailed",
  "url": "https://api.aikousao.com/files/r/...pdf?sign=...",
  "expires_at": "2026-10-29T10:35:00Z",
  "content_type": "application/pdf"
}

Webhooks

Webhook

报告完成后主动通知你的服务端，减少轮询。Webhook 带签名，失败自动重试。

POST/v1/webhooks配置回调

字段	类型	说明
`url`	string	HTTPS 回调地址
`events`	string[]	`report.ready`、`job.failed`、`job.status_changed`
`secret`	string	用于 HMAC-SHA256 签名

POST https://your-server.com/webhook
X-Signature: t=1793255525,v1=5f2c...

{
  "id": "evt_3k8m",
  "event": "report.ready",
  "job_id": "job_9d2x7q",
  "report_ids": ["rep_7k4m2p"],
  "occurred_at": "2026-10-29T10:05:00Z"
}

签名校验：HMAC-SHA256(secret, t + "." + raw_body)，比较 v1；时间戳超过 5 分钟拒绝。

Usage

用量

GET/v1/usage?from=2026-10-01&to=2026-10-31租户用量

{
  "tenant_id": "ten_2x9",
  "from": "2026-10-01",
  "to": "2026-10-31",
  "scans": 128,
  "ai_tasks": 128,
  "api_calls": 3420,
  "storage_bytes": 2147483648
}

Errors

错误码

所有错误使用统一结构，不返回厂商原始错误、域名或 token。

{
  "code": "SCAN_INCOMPLETE",
  "message": "必须提交 8 张影像",
  "request_id": "req_8d2k",
  "details": { "received": 7 }
}

HTTP	code	说明	可重试
400	`VALIDATION_ERROR`	参数校验失败	否
401	`AUTH_INVALID`	API Key 无效	否
403	`FORBIDDEN`	无权限 / 越权租户	否
404	`NOT_FOUND`	资源不存在	否
409	`DUPLICATE_PATIENT`	手机号已存在	否
422	`SCAN_INCOMPLETE`	影像不足 8 张或类型错误	否
429	`RATE_LIMITED`	超过租户限流	是（Retry-After）
429	`QUEUE_FULL`	队列已满，请稍后	是
503	`VENDOR_UNAVAILABLE`	上游暂时不可用	是
500	`INTERNAL_ERROR`	平台内部错误	视情况

Limits

限流与配额

按租户限流，保护平台与厂商 AI 并发。响应头会返回当前配额。

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1793255580
Retry-After: 30   # 429 时返回

API 限流

按租户/接口维度限制 RPS，默认 10–30 RPS，管理端可调。

AI 队列

每租户最多 1–2 个并发任务；队列超阈值时返回 QUEUE_FULL。

存储配额

按租户限制 10 年存储用量；超限前预警，支持扩容。

Compliance

数据与合规

租户隔离

所有患者、扫描、报告、文件按 tenant 隔离；数据库行级安全，API Key 绑定租户。

加密与访问

TLS 传输、对象存储加密、患者手机号/姓名加密存储；下载使用短时签名 URL。

同意与留存

创建患者需 consent=true；默认留存 10 年，可按租户配置删除/匿名化。

医疗声明

AI 报告仅供临床参考，不替代执业医师诊断；报告内包含免责声明。

平台不向客户端暴露厂商域名、凭证、原始错误或品牌；影像与报告统一镜像到自有对象存储。

Changelog

更新日志

版本	日期	内容
`v1.0`	2026-10-29	首版：患者、扫描、异步任务、报告、Webhook、用量、错误码、限流。

一次接入，获得完整口腔 AI 报告能力

概览

异步任务

多租户隔离

完全去品牌

快速开始

1. 获取 API Key

2. 创建患者

3. 提交扫描

4. 查询任务

5. 下载报告

认证与安全

权限范围（Scopes）

异步任务模型

Job 对象

患者

扫描上传

标准位

任务状态

报告

简易报告 · simple

详细报告 · detailed

Webhook

用量

错误码

限流与配额

API 限流

AI 队列

存储配额

数据与合规

租户隔离

加密与访问

同意与留存

医疗声明

更新日志