声纹信息

平台提供说话人声纹（VPR）注册与管理能力。上传说话人音频完成注册后，将获得 feature_id，可在 实时语音转写 或 语音转写（异步） 中通过 speaker_ids 参数注入已注册声纹，实现指定说话人识别。

使用流程

1. 准备注册音频：准备一段说话人音频，转为 Base64 后作为 audio_data 传入。

• 支持格式：wav、mp3
• wav 需为 16 kHz、16 bit、单声道，时长 5～20 秒
• Base64 编码后不超过 5 MB

2. 注册声纹：调用 注册声纹 接口，获取 feature_id。
3. 查询 / 更新（可选）：通过 查询声纹 查看已注册列表；通过 更新声纹 修改备注或重新上传音频。
4. 在转写中使用：将 feature_id 填入转写请求的 speaker_ids 数组，开启说话人分离后生效。
5. 删除声纹（可选）：不再使用时调用 删除声纹 接口。

过程示例

请将 API_KEY 写入环境变量，并将音频路径替换为本地实际文件。

1. 准备音频（Base64）

声纹接口请求体为 JSON，audio_data 需传入音频文件的 Base64 字符串（不含 data:audio/wav;base64, 等前缀）。

"""
本示例用于将本地 wav 音频编码为 Base64，供注册/更新接口使用。
注意：需为 16 kHz、16 bit、单声道，时长 5～20 秒。
"""
import base64

audio_path = "/path/to/speaker.wav"

with open(audio_path, "rb") as f:
    audio_data = base64.b64encode(f.read()).decode("utf-8")

print(f"base64 length: {len(audio_data)}")

2. 注册声纹

注册成功后响应中的 feature_id 即为后续转写 speaker_ids 使用的声纹 ID。

"""
本示例用于注册说话人声纹。
注意：需要先将密钥信息写入环境变量 `API_KEY`。
"""
import requests
import base64
import os

api_key = os.getenv("API_KEY")
url = "https://maas-api.unisound.com/v1/vpr/register"

with open("/path/to/speaker.wav", "rb") as f:
    audio_data = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "audio_data": audio_data,
    "audio_type": "wav",
    "feature_info": "张三"
}
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
result = response.json()
print(result)

feature_id = result.get("feature_id")
print("feature_id:", feature_id)

成功响应示例

{
  "feature_id": "vpr_20250625_abc123def456",
  "feature_info": "张三",
  "created_at": "2025-06-25 14:30:00",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

3. 更新声纹

更新已注册声纹的备注和/或音频；feature_info 与 audio_data 至少填一项。仅更新备注时仍需传入 audio_type。

"""
本示例用于更新声纹备注（也可同时传入 audio_data 重新提取声纹向量）。
注意：需要设置环境变量 `API_KEY`，并将 feature_id 替换为注册返回的实际值。
"""
import requests
import os

api_key = os.getenv("API_KEY")
url = "https://maas-api.unisound.com/v1/vpr/update"
feature_id = "vpr_20250625_abc123def456"

payload = {
    "feature_id": feature_id,
    "audio_type": "wav",
    "feature_info": "张三（更新）"
}
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

4. 查询声纹

支持两种模式：

4.1 分页查询

"""
本示例用于分页查询已注册声纹列表。
"""
import requests
import os

api_key = os.getenv("API_KEY")
url = "https://maas-api.unisound.com/v1/vpr/query"

payload = {
    "page_index": 1,
    "page_size": 20
}
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

4.2 按 ID 查询

"""
本示例用于按 feature_id 列表精确查询。
"""
import requests
import os

api_key = os.getenv("API_KEY")
url = "https://maas-api.unisound.com/v1/vpr/query"

payload = {
    "describe_mode": 0,
    "feature_ids": [
        "vpr_20250625_abc123def456",
        "vpr_20250625_def789ghi012"
    ]
}
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

5. 删除声纹

删除指定 feature_id 对应的声纹。声纹不存在时忽略，仍返回成功。

"""
本示例用于删除已注册声纹。
"""
import requests
import os

api_key = os.getenv("API_KEY")
url = "https://maas-api.unisound.com/v1/vpr/delete"
feature_id = "vpr_20250625_abc123def456"

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

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

完整流程示例（Python）

以下脚本串联注册 → 更新 → 分页查询 → 按 ID 查询 → 删除，便于一次性验证四个接口。

"""
声纹管理完整流程示例。
使用前请设置环境变量 API_KEY，并将 AUDIO_PATH 替换为本地 wav 文件路径。
"""
import base64
import os
import requests

API_KEY = os.getenv("API_KEY")
BASE_URL = "https://maas-api.unisound.com/v1/vpr"
AUDIO_PATH = "/path/to/speaker.wav"

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


def load_audio_base64(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")


def assert_success(resp: requests.Response) -> dict:
    resp.raise_for_status()
    body = resp.json()
    if body.get("base_resp", {}).get("status_code") != 0:
        raise RuntimeError(f"business error: {body}")
    return body


# 1. 注册
register_resp = assert_success(requests.post(
    f"{BASE_URL}/register",
    headers=headers,
    json={
        "audio_data": load_audio_base64(AUDIO_PATH),
        "audio_type": "wav",
        "feature_info": "demo speaker",
    },
))
feature_id = register_resp["feature_id"]
print("register feature_id:", feature_id)

# 2. 更新备注
assert_success(requests.post(
    f"{BASE_URL}/update",
    headers=headers,
    json={
        "feature_id": feature_id,
        "audio_type": "wav",
        "feature_info": "demo speaker updated",
    },
))
print("update ok")

# 3. 分页查询
page_resp = assert_success(requests.post(
    f"{BASE_URL}/query",
    headers=headers,
    json={"page_index": 1, "page_size": 20},
))
print("page total_count:", page_resp.get("total_count"))

# 4. 按 ID 查询
id_resp = assert_success(requests.post(
    f"{BASE_URL}/query",
    headers=headers,
    json={"describe_mode": 0, "feature_ids": [feature_id]},
))
print("query by id count:", len(id_resp.get("list", [])))

# 5. 删除
assert_success(requests.post(
    f"{BASE_URL}/delete",
    headers=headers,
    json={"feature_id": feature_id},
))
print("delete ok")

在转写中使用 feature_id

注册成功后，将 feature_id 传入转写接口的 speaker_ids 参数（字符串数组）：

转写结果中，命中已注册声纹的句子会返回对应的 feature_id 作为说话人标识。

常见问题

Q：audio_data 传 mp3 可以吗？

可以，audio_type 填 mp3 即可。建议使用清晰、无背景噪声的单人语音。

Q：注册失败返回 100999 怎么办？

请从响应头 Trace-Id 获取链路 ID 并联系技术支持排查（可能为引擎超时或内部异常）。

Q：删除了声纹，转写还能识别吗？

不能。删除后 speaker_ids 中对应 ID 将无法命中，转写会退化为引擎默认的说话人分离行为。

Q：API 详细字段与错误码在哪里查看？

见 声纹管理 API 参考。