Quality Check API Documentation

通话质检服务 API 接入文档

一、概述

通话质检服务，提交通话录音 URL 或上传音频文件，系统自动完成语音转文字和合规分析，返回结构化质检结果。

1.0 接入信息

项目	值
Base URL	`https://api.multiheif.com`

1.1 认证方式

所有接口使用 API Key 认证，在请求 Header 中传递：

X-API-Key: your-api-key

API Key 由管理员分配，每个 Key 仅可查询自己名下的任务。

1.2 约束与限制

约束项	限制
音频文件大小	最大 20MB
请求频率	60 次/分钟 (每个 API Key)
批量提交	每批最多 50 个任务
支持格式	MP3, WAV, FLAC, OGG, M4A 等常见音频格式

二、接口文档

POST /api/tasks — 提交质检任务

提交一个音频 URL，系统异步完成转录和质检分析。

请求体：

{
  "audio_url": "https://example.com/call-recording.mp3",
  "callback_url": "https://your-server.com/webhook/qa-result"
}

字段	类型	必填	说明
`audio_url`	string (URL)	是	音频文件下载地址
`callback_url`	string (URL)	否	任务完成/失败后系统主动回调的地址

响应 (201 Created)：

{
  "task_id": "21ca641d-1a38-495a-88fc-04ac8b8f2f67",
  "status": "pending",
  "created_at": "2026-02-04T10:56:29.613460Z"
}

状态流转：pending → processing → completed / failed

如果提供了 callback_url，任务完成或最终失败后系统会主动 POST 回调，无需轮询。

POST /api/tasks/batch — 批量提交任务

一次提交多个音频 URL，每批最多 50 个。

请求体：

{
  "audio_urls": [
    "https://example.com/call-1.mp3",
    "https://example.com/call-2.mp3",
    "https://example.com/call-3.mp3"
  ],
  "callback_url": "https://your-server.com/webhook/qa-result"
}

字段	类型	必填	说明
`audio_urls`	string[]	是	音频 URL 列表，最多 50 个
`callback_url`	string (URL)	否	共享回调地址，每个任务完成后分别回调

响应 (201 Created)：

{
  "tasks": [
    {
      "task_id": "21ca641d-1a38-495a-88fc-04ac8b8f2f67",
      "status": "pending",
      "created_at": "2026-02-04T10:56:29.613460Z"
    },
    {
      "task_id": "8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "status": "pending",
      "created_at": "2026-02-04T10:56:29.615123Z"
    }
  ]
}

POST /api/tasks/upload — 上传音频文件

直接上传音频文件提交质检，适用于无法提供下载 URL 的场景。

请求：multipart/form-data

字段	类型	必填	说明
`file`	file	是	音频文件 (最大 20MB)
`callback_url`	string	否	回调地址

curl 示例：

curl -X POST https://api.multiheif.com/api/tasks/upload \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/recording.mp3" \
  -F "callback_url=https://your-server.com/webhook/qa-result"

响应 (201 Created)：

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "created_at": "2026-02-04T10:56:29.613460Z"
}

GET /api/tasks/{task_id} — 查询任务结果

轮询任务状态，完成后返回质检结果。仅可查询当前 API Key 名下的任务。

路径参数：task_id (UUID，由提交接口返回)

查询参数：

参数	类型	默认	说明
`include_transcript`	bool	false	设为 true 时返回完整转录文本

响应 — 完成时 (200 OK)：

{
  "task_id": "21ca641d-1a38-495a-88fc-04ac8b8f2f67",
  "status": "completed",
  "result": {
    "insult_threats_intimidation": {
      "detected": "none",
      "statements": []
    },
    "impersonating": {
      "detected": "false",
      "statements": []
    },
    "privately_contact": {
      "detected": "false",
      "statements": []
    },
    "complaint_level": {
      "detected": "low",
      "statements": ["Don't charge me for overdue."]
    },
    "social_media_exposure": {
      "detected": "false",
      "statements": []
    },
    "false_promise": {
      "detected": "false",
      "statements": []
    },
    "mocking_tone": {
      "detected": "true",
      "statements": ["You don't do expectation like that."]
    },
    "normal": "false",
    "conversation_summary": "The call is a debt collection attempt. The agent uses a mocking tone when the customer explains their payment expectation."
  },
  "created_at": "2026-02-04T10:56:29.613460Z",
  "completed_at": "2026-02-04T10:56:46.600990Z"
}

响应 — 失败时：

{
  "task_id": "21ca641d-1a38-495a-88fc-04ac8b8f2f67",
  "status": "failed",
  "error_message": "Download failed: 404 Not Found",
  "created_at": "2026-02-04T10:56:29.613460Z"
}

响应 — 处理中：

{
  "task_id": "21ca641d-1a38-495a-88fc-04ac8b8f2f67",
  "status": "processing",
  "created_at": "2026-02-04T10:56:29.613460Z"
}

三、Webhook 回调

如果提交任务时设置了 callback_url，系统会在任务完成或最终失败后主动 POST 结果到该地址。

3.1 回调请求格式

Headers：Content-Type: application/json

成功回调：

{
  "task_id": "21ca641d-1a38-495a-88fc-04ac8b8f2f67",
  "status": "completed",
  "result": { ... },
  "completed_at": "2026-02-04T10:56:46.600990Z"
}

失败回调：

{
  "task_id": "21ca641d-1a38-495a-88fc-04ac8b8f2f67",
  "status": "failed",
  "error_message": "Transcription failed: audio format not supported"
}

3.2 回调重试机制

回调失败自动重试 3 次，采用指数退避 (2s, 4s, 8s)
回调超时时间 10 秒
请确保回调地址返回 2xx 状态码表示成功接收

四、质检结果数据结构

4.1 结果字段说明

质检结果 (result) 包含 7 个检测类别 + 综合判定 + 通话摘要。

字段	类型	取值	说明
`insult_threats_intimidation`	object	detected: "none" / "insult" / "threats" / "intimidation"	侮辱/威胁/恐吓
`impersonating`	object	detected: "true" / "false"	冒充官方身份
`privately_contact`	object	detected: "true" / "false"	要求私下联系
`complaint_level`	object	detected: "none" / "low" / "medium" / "high" / "already_complained"	客户投诉等级
`social_media_exposure`	object	detected: "true" / "false"	威胁在社交媒体曝光
`false_promise`	object	detected: "true" / "false"	虚假承诺 (将付款与结果关联)
`mocking_tone`	object	detected: "true" / "false"	嘲讽/命令语气
`normal`	string	"true" / "false"	综合判定，所有类别均无违规时为 "true"
`conversation_summary`	string	—	通话摘要 (英文，≤40 词)

每个检测类别包含：

detected：检测结果
statements：触发该判定的原始语句列表 (英文)

4.2 normal 判定逻辑

normal = "true" 当且仅当以下条件全部满足：

insult_threats_intimidation.detected == "none"
impersonating.detected == "false"
privately_contact.detected == "false"
complaint_level.detected == "none"
social_media_exposure.detected == "false"
false_promise.detected == "false"
mocking_tone.detected == "false"

任一条件不满足，normal 为 "false"。

五、错误码

HTTP 状态码	说明
`201`	任务创建成功
`200`	查询成功
`400`	请求参数错误 (音频文件过大 / 批量超过50个 / URL 无效)
`401`	API Key 无效或未提供
`403`	API Key 已被禁用
`404`	任务不存在或不属于当前 API Key
`429`	请求频率超限 (60次/分钟)

六、使用示例

提交单个任务

curl -X POST https://api.multiheif.com/api/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"audio_url": "https://example.com/call-recording.mp3"}'

提交任务 + Webhook 回调

curl -X POST https://api.multiheif.com/api/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "audio_url": "https://example.com/call-recording.mp3",
    "callback_url": "https://your-server.com/webhook/qa-result"
  }'

批量提交

curl -X POST https://api.multiheif.com/api/tasks/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "audio_urls": [
      "https://example.com/call-1.mp3",
      "https://example.com/call-2.mp3",
      "https://example.com/call-3.mp3"
    ],
    "callback_url": "https://your-server.com/webhook/qa-result"
  }'

上传文件

curl -X POST https://api.multiheif.com/api/tasks/upload \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/recording.mp3"

查询结果

curl https://api.multiheif.com/api/tasks/21ca641d-1a38-495a-88fc-04ac8b8f2f67 \
  -H "X-API-Key: your-api-key"

典型集成流程

方式一：轮询模式

调用 POST /api/tasks 提交音频 URL，获取 task_id
轮询 GET /api/tasks/{task_id}，直到 status 为 completed 或 failed
从 result 中读取质检结果，normal 字段表示综合是否合规

方式二：Webhook 回调模式推荐

调用 POST /api/tasks 提交音频 URL，同时传入 callback_url
系统处理完成后主动 POST 结果到 callback_url
在回调接口中处理质检结果，无需轮询

方式三：批量 + 回调

调用 POST /api/tasks/batch 一次提交多个音频 URL + 共享 callback_url
各任务独立处理，完成后分别回调
通过 task_id 区分不同任务的结果

Quality Check API Documentation

一、概述

1.0 接入信息

1.1 认证方式

1.2 约束与限制

二、接口文档

POST /api/tasks — 提交质检任务

POST /api/tasks/batch — 批量提交任务

POST /api/tasks/upload — 上传音频文件

GET /api/tasks/{task_id} — 查询任务结果

三、Webhook 回调

3.1 回调请求格式

3.2 回调重试机制

四、质检结果数据结构

4.1 结果字段说明

4.2 normal 判定逻辑

五、错误码

六、使用示例

提交单个任务

提交任务 + Webhook 回调

批量提交

上传文件

查询结果

典型集成流程

方式一：轮询模式

方式二：Webhook 回调模式 推荐

方式三：批量 + 回调

方式二：Webhook 回调模式推荐