You need to enable JavaScript to run this app.
导航
语音技术
  • 文档首页
    • /
  • 语音技术

鉴权方法

最近更新时间：2023.06.29 14:52:48

首次发布时间：2023.06.29 14:52:48

我的收藏
Resource ID

请求接口时，需要根据请求的服务类型，携带对应的 Resource-Id Header。

服务类型Resource ID
长文本合成volc.tts_async.default
长文本合成（带情感预测）volc.tts_async.emotion
鉴权

说明

目前提供 Bearer Token 和 HMAC256 两种鉴权方式，选择其中一种即可。推荐使用较简单的 bearer token 鉴权。

appid、access_token 和 secret_key 由平台分配，通过控制台创建应用获得，可参考文档快速入门。

Bearer Token

在请求接口时，须在发送的 GET 或 POST 请求中加上鉴权相关的 Authorization header，格式为Bearer; {token}。

示例

GET /api/v1/tts_async/query?appid=&task_id= HTTP/1.1
Host: openspeech.bytedance.com
Accept: */*
User-Agent: curl/7.54.0
Resource-Id: volc.tts_async.default
Authorization: Bearer; FYaWxBiJnuh-0KBTS00KCo73rxmDnalivd1UDSD-W5E=

Authorization header 的格式是 Bearer; {token}

  • Bearer：鉴权方法名
  • token: 控制台获取的Access Token

注意

鉴权方法名和 token 之间用 ; 分隔。

HMAC256

相比于 token 鉴权，signature 还需在 Authorization header 中加入 access_token、mac、h 等信息。如以下示例：

GET /api/v1/tts_async/query?appid=fake_appid&task_id=4ad10259-0e0a-443e-963d-3b27fc69d910 HTTP/1.1
Host: openspeech.bytedance.com
Accept: */*
User-Agent: curl/7.54.0
Resource-Id: volc.tts_async.default
Authorization: HMAC256; access_token="fake_token"; mac="PyUc1hUckhGloa55HyRS3nlYrKWNEB_jOTlfyIHnwVc"; h="Host,Resource-Id"

Authorization header 由四个部分组成：

  • HMAC256：授权方法名
  • fake_token: 控制台获取的 Access Token
  • mac: 消息验证码，使用 HMAC-SHA256 算法生成的签名串，再经过 base64 url 编码，其中 base64 编码后的值是否带有填充的 “=” 并不影响判断结果。生成签名串的方法见下一节。
  • h:（可选）自定义需要签名的 header 列表，用 ,分隔

生成签名串

使用 HMAC-SHA256 算法对输入的字符串用 secret_key 作为 key进行加密,然后使用 base64 url 对结果进行编码。
待加密字符串分为三个部分：

  1. HTTP 请求行
  2. Headers，默认使用 Host 加密，但如果指定了 h，则根据 h 添加
  3. Body（如果存在）

示例模版如下（添加了换行符以提高可读性，输入字符串的实际换行符使用 \n 进行转义）：

<Method> <URI> <Proto>\n
<Header1>\n
<Header2>\n
...\n
<Body>

注意

  1. 如果Body不存在，则需要以换行符\n结尾
  2. Headers 必须按照自定义 header h 里指定的顺序加入待加密字符串。
  3. 如果指定了 header 但是请求中找不到，server 端会返回 error。
  4. 如果 header 被多次指定，则必须被多次添加到待加密字符串中。

示例

若原始请求为：

GET /api/v1/tts_async/query?appid=fake_appid&task_id=4ad10259-0e0a-443e-963d-3b27fc69d910 HTTP/1.1
Host: openspeech.bytedance.com
User-Agent: curl/7.54.0
Resource-Id: volc.tts_async.default

假设 secret_key 为下面以 16 进制表示的二进制串(该二进制串对应的原始文本为"super_secret_key")：

73 75 70 65 72 5f 73 65 63 72 65 74 5f 6b 65 79

指定 h 为 "Host,Resource-Id"，则原始待加密字符串为：

GET /api/v1/tts_async/query?appid=fake_appid&task_id=4ad10259-0e0a-443e-963d-3b27fc69d910 HTTP/1.1
openspeech.bytedance.com
volc.tts_async.default
(空行)

经过 HMAC-SHA256 加密 以及 base64 url 编码后，计算得出 mac 为：

PyUc1hUckhGloa55HyRS3nlYrKWNEB_jOTlfyIHnwVc

假定 access_token 为 “fake_token” 所以最终的请求为：

GET /api/v1/tts_async/query?appid=fake_appid&task_id=4ad10259-0e0a-443e-963d-3b27fc69d910 HTTP/1.1
Host: openspeech.bytedance.com
User-Agent: curl/7.54.0
Resource-Id: volc.tts_async.default
Authorization: HMAC256; access_token="fake_token"; mac="PyUc1hUckhGloa55HyRS3nlYrKWNEB_jOTlfyIHnwVc"; h="Host,Resource-Id"