語音或音頻轉(zhuǎn)文字或轉(zhuǎn)字幕生成接口開發(fā)文檔

1. 接口概述

本接口為酷虎云提供的音頻轉(zhuǎn)文字（Speech-to-Text, STT）服務(wù)接口，支持通過提交音頻URL的方式批量發(fā)起轉(zhuǎn)寫任務(wù)，并可查詢?nèi)蝿?wù)狀態(tài)及獲取轉(zhuǎn)寫結(jié)果（含可導出為SRT格式的字幕信息），適用于需要將音頻內(nèi)容轉(zhuǎn)化為文本或字幕的開發(fā)場景。

2. 接口基礎(chǔ)信息

項目? ? ? ? ? ? ? ? 內(nèi)容? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

-------------------------------------------------------------------------------------------

接口地址? ? ? ? `https://#/api/stt/audiototexturls`? ? ? ? ? ? ? ? ? ?

請求方式? ? ? ? HTTP POST? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

返回格式? ? ? ? application/json? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

Content-Type? ? application/json（請求頭必須包含此參數(shù)，否則會導致請求失?。? ? ? ? ?

在線調(diào)試工具? ? apifox

3. 請求參數(shù)說明

接口請求參數(shù)分為URL參數(shù)和請求體參數(shù)，需根據(jù)`type`（任務(wù)類型）傳入對應(yīng)參數(shù)。

3.1 通用URL參數(shù)（必傳）

所有請求均需在URL中攜帶以下參數(shù)：

參數(shù)名? 是否必填? 類型? ? 示例值? ? ? ? ? ? ? ? ? ? ? ? ? 說明? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

---------------------------------------------------------------------------------------------------------------------------------

key? ? 是? ? ? ? string? 35kj5jnlj53453kl5j43nj5? ? ? ? ? 接口密鑰，用于身份驗證，可在酷虎云控制臺「密鑰管理」頁面獲取。? ? ?

type? ? 是? ? ? ? string? start / query? ? ? ? ? ? ? ? ? ? 任務(wù)類型：<br>- `start`：提交音頻轉(zhuǎn)寫任務(wù)，返回任務(wù)ID；<br>- `query`：查詢指定任務(wù)的狀態(tài)及轉(zhuǎn)寫結(jié)果。

3.2 按任務(wù)類型的請求體參數(shù)

3.2.1 提交任務(wù)（type=start）

當`type=start`時，需在請求體中傳入音頻URL列表，用于批量發(fā)起轉(zhuǎn)寫任務(wù)。

參數(shù)名? ? ? 是否必填? 類型? ? 示例值? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 說明? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

--------------------------------------------------------------------------------------------------------------------------------------------------------------------

audio_urls? 是? ? ? ? array? ["https://#/audio1.mp3", "https://#/audio2.mp3"]? 音頻URL數(shù)組，支持批量提交多個音頻地址，僅支持`http/https`協(xié)議的URL，音頻格式需為MP3（其他格式可能導致識別失?。?。

請求體示例：

```json

{

? "audio_urls": [

? ? "https://#/audio_sample1.mp3",

? ? "https://#/audio_sample2.mp3"

? ]

}

```

3.2.2 查詢?nèi)蝿?wù)（type=query）

當`type=query`時，需在請求體中傳入任務(wù)ID，用于查詢該任務(wù)的詳細信息（含轉(zhuǎn)寫結(jié)果）。

參數(shù)名? ? 是否必填? 類型? ? 示例值? ? ? ? ? ? ? ? ? ? ? ? ? 說明? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

-----------------------------------------------------------------------------------------------------------------------------------

task_id? 是? ? ? ? string? b68b6285901bb8621f680fbabe796d6e? 任務(wù)ID，由`type=start`請求返回，用于唯一標識一個轉(zhuǎn)寫任務(wù)。? ? ? ? ?

請求體示例：

```json

{

? "task_id": "b68b6285901bb8621f680fbabe796d6e"

}

```

4. 返回參數(shù)說明

所有請求的返回格式均為JSON，包含狀態(tài)碼、狀態(tài)信息及對應(yīng)業(yè)務(wù)數(shù)據(jù)，不同任務(wù)類型的返回數(shù)據(jù)結(jié)構(gòu)略有差異。

4.1 通用返回字段（所有請求均包含）

字段名? ? ? 類型? ? 說明? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

-------------------------------------------------------------------------------------------

code? ? ? ? int? ? ? 狀態(tài)碼：<br>- 200：請求成功；<br>- 非200：請求失敗（具體原因見`msg`）。

msg? ? ? ? string? 狀態(tài)信息，描述請求成功/失敗的原因（如“任務(wù)提交成功”“任務(wù)ID不存在”）。?

exec_time? float? ? 接口執(zhí)行耗時（單位：秒），用于性能參考。? ? ? ? ? ? ? ? ? ? ? ? ? ?

user_ip? ? string? 客戶端IP地址，用于排查請求來源問題。? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

debug? ? ? string/array? 調(diào)試數(shù)據(jù)，僅在接口異常時返回，包含詳細錯誤日志（非必返字段）。? ? ?

4.2 按任務(wù)類型的業(yè)務(wù)返回字段

4.2.1 提交任務(wù)（type=start）返回

當`type=start`且請求成功（code=200）時，返回數(shù)據(jù)中包含任務(wù)ID，用于后續(xù)查詢。

字段名? ? 類型? ? 說明? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

-----------------------------------------------------------------------------------------

task_id? string? 任務(wù)ID，唯一標識當前提交的轉(zhuǎn)寫任務(wù)，需保存用于后續(xù)查詢?nèi)蝿?wù)結(jié)果。? ? ?

data? ? ? string? 任務(wù)提交結(jié)果描述（如“批量任務(wù)已創(chuàng)建，共2個音頻文件”）。? ? ? ? ? ? ?

返回示例（成功）：

```json

{

? "code": 200,

? "msg": "任務(wù)提交成功",

? "data": "批量任務(wù)已創(chuàng)建，共2個音頻文件",

? "task_id": "b68b6285901bb8621f680fbabe796d6e",

? "exec_time": 0.32,

? "user_ip": "123.45.67.89",

? "debug": ""

}

```

4.2.2 查詢?nèi)蝿?wù)（type=query）返回

當`type=query`且請求成功（code=200）時，返回數(shù)據(jù)中包含任務(wù)狀態(tài)、音頻信息及轉(zhuǎn)寫結(jié)果（含字幕信息）。

字段名? ? ? ? 類型? ? 說明? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

---------------------------------------------------------------------------------------------

data? ? ? ? ? object? 任務(wù)結(jié)果數(shù)據(jù)集，包含以下子字段（僅任務(wù)完成時返回完整數(shù)據(jù)）：? ? ? ? ?

├─ display? ? array? ? 識別信息組，每個元素對應(yīng)一段音頻的轉(zhuǎn)寫詳情（多音頻任務(wù)返回多個元素）。

│? ├─ source? string? 音頻源URL，對應(yīng)提交時的`audio_urls`中的某個地址。? ? ? ? ? ? ? ? ? ?

│? ├─ seconds string? 音頻時長（單位：秒），如“125.3”表示125秒300毫秒。? ? ? ? ? ? ? ? ?

│? └─ phrases array? ? 字幕斷句列表，每個元素為一段字幕的詳細信息：? ? ? ? ? ? ? ? ? ? ? ?

│? ? ├─ text? ? ? ? string? 該段字幕的文本內(nèi)容。? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

│? ? ├─ confidence? string? 文本識別置信度（0-100），值越高表示識別結(jié)果越準確。? ? ? ? ? ? ? ? ?

│? ? ├─ start_time? string? 字幕開始時間（格式：時:分:秒.毫秒），如“00:01:45.300”。? ? ? ? ? ?

│? ? └─ duration? ? string? 字幕持續(xù)時間（格式：時:分:秒.毫秒），如“00:00:08.500”。? ? ? ? ? ?

task_id? ? ? string? 任務(wù)ID，與請求時傳入的`task_id`一致。? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

返回示例（任務(wù)完成）：

```json

{

? "code": 200,

? "msg": "任務(wù)查詢成功（已完成）",

? "data": {

? ? "display": [

? ? ? {

? ? ? ? "source": "https://#/audio_sample1.mp3",

? ? ? ? "seconds": "125.3",

? ? ? ? "phrases": [

? ? ? ? ? {

? ? ? ? ? ? "text": "大家好，歡迎使用酷虎云STT接口",

? ? ? ? ? ? "confidence": "98.5",

? ? ? ? ? ? "start_time": "00:00:02.100",

? ? ? ? ? ? "duration": "00:00:05.200"

? ? ? ? ? },

? ? ? ? ? {

? ? ? ? ? ? "text": "本接口支持批量音頻轉(zhuǎn)寫和SRT字幕導出",

? ? ? ? ? ? "confidence": "97.8",

? ? ? ? ? ? "start_time": "00:00:07.500",

? ? ? ? ? ? "duration": "00:00:06.800"

? ? ? ? ? }

? ? ? ? ]

? ? ? },

? ? ? {

? ? ? ? "source": "https://#/audio_sample2.mp3",

? ? ? ? "seconds": "89.6",

? ? ? ? "phrases": [

? ? ? ? ? {

? ? ? ? ? ? "text": "查詢?nèi)蝿?wù)時需傳入正確的任務(wù)ID",

? ? ? ? ? ? "confidence": "99.1",

? ? ? ? ? ? "start_time": "00:00:01.300",

? ? ? ? ? ? "duration": "00:00:04.700"

? ? ? ? ? }

? ? ? ? ]

? ? ? }

? ? ]

? },

? "task_id": "b68b6285901bb8621f680fbabe796d6e",

? "exec_time": 0.58,

? "user_ip": "123.45.67.89",

? "debug": ""

}

```

返回示例（任務(wù)處理中）：

```json

{

? "code": 200,

? "msg": "任務(wù)查詢成功（處理中）",

? "data": "當前任務(wù)進度：60%，請稍后查詢",

? "task_id": "b68b6285901bb8621f680fbabe796d6e",

? "exec_time": 0.21,

? "user_ip": "123.45.67.89",

? "debug": ""

}

```

5. 常見錯誤碼及解決方案

錯誤碼? 錯誤信息示例? ? ? ? ? ? ? ? ? ? ? 可能原因及解決方案? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

-----------------------------------------------------------------------------------------------------------------------------

400? ? "參數(shù)缺失：key不能為空"? ? ? ? ? ? 未在URL中傳入`key`參數(shù)，需從控制臺獲取密鑰并補充到請求URL中。? ? ? ? ? ? ? ? ? ?

400? ? "參數(shù)錯誤：type必須為start或query"? `type`參數(shù)值錯誤，需修正為`start`（提交任務(wù)）或`query`（查詢?nèi)蝿?wù)）。? ? ? ? ? ? ?

401? ? "密鑰無效：key不存在或已過期"? ? `key`錯誤或已失效，需登錄控制臺檢查密鑰是否正確，或重新生成新密鑰。? ? ? ? ? ? ?

403? ? "無權(quán)限：當前密鑰無STT接口訪問權(quán)限"? 密鑰未開通STT接口權(quán)限，需在控制臺「接口權(quán)限管理」中為該密鑰開通權(quán)限。? ? ? ? ? ?

404? ? "任務(wù)不存在：task_id無效"? ? ? ? 查詢時傳入的`task_id`錯誤或已過期，需確認`task_id`是否與提交任務(wù)時返回的一致。? ?

415? ? "不支持的媒體類型：Content-Type必須為application/json"? 請求頭未設(shè)置`Content-Type: application/json`，需補充該請求頭。? ? ? ? ? ? ? ? ?

500? ? "服務(wù)器錯誤：音頻URL無法訪問"? ? 提交的`audio_urls`中存在無法訪問的URL，需檢查音頻地址是否有效、是否支持外部訪問。

6. 接口調(diào)用流程示例

以“提交轉(zhuǎn)寫任務(wù)→查詢?nèi)蝿?wù)結(jié)果→導出SRT字幕”為例，完整流程如下：

步驟1：提交轉(zhuǎn)寫任務(wù)（type=start）

1. 構(gòu)造請求URL：`https://#/api/stt/audiototexturls?key=你的密鑰&type=start`

2. 設(shè)置請求頭：`Content-Type: application/json`

3. 構(gòu)造請求體（含2個音頻URL）：

? ```json

? {

? ? "audio_urls": [

? ? ? "https://#/audio1.mp3",

? ? ? "https://#/audio2.mp3"

? ? ]

? }

? ```

4. 發(fā)送POST請求，獲取返回的`task_id`（如`b68b6285901bb8621f680fbabe796d6e`）。

步驟2：查詢?nèi)蝿?wù)結(jié)果（type=query）

1. 構(gòu)造請求URL：`https://#/api/stt/audiototexturls?key=你的密鑰&type=query`

2. 設(shè)置請求頭：`Content-Type: application/json`

3. 構(gòu)造請求體（傳入步驟1獲取的`task_id`）：

? ```json

? {

? ? "task_id": "b68b6285901bb8621f680fbabe796d6e"

? }

? ```

4. 發(fā)送POST請求，若返回`msg`為“任務(wù)查詢成功（已完成）”，則從`data.display[0].phrases`中獲取第一段音頻的字幕數(shù)據(jù)。

步驟3：導出SRT字幕

根據(jù)`phrases`中的`start_time`（開始時間）、`duration`（持續(xù)時間）和`text`（文本），按SRT格式拼接內(nèi)容，示例如下：

```srt

1

00:00:02.100 --> 00:00:07.300? // 開始時間 + 持續(xù)時間 = 結(jié)束時間（2.1+5.2=7.3）

大家好，歡迎使用酷虎云STT接口

2

00:00:07.500 --> 00:00:14.300? // 7.5+6.8=14.3

本接口支持批量音頻轉(zhuǎn)寫和SRT字幕導出

```

7. 注意事項

1. 密鑰安全：`key`為接口訪問憑證，請勿泄露給第三方，若懷疑密鑰泄露，需立即在控制臺重新生成。

2. 音頻限制：

? - 僅支持`http/https`協(xié)議的音頻URL，本地文件需先上傳至服務(wù)器并獲取公網(wǎng)可訪問的URL；

? - 推薦音頻格式為MP3，其他格式（如WAV、AAC）可能導致識別成功率下降；

? - 單條音頻時長建議不超過30分鐘，超長音頻可能導致任務(wù)處理超時。

3. 查詢頻率：任務(wù)提交后需等待處理（通常1-5分鐘，視音頻時長而定），建議間隔30秒-1分鐘查詢一次，避免高頻請求導致接口限流。

4. SRT導出：`phrases`中的`start_time`為字幕開始時間，`duration`為持續(xù)時間，需自行計算字幕結(jié)束時間（開始時間+持續(xù)時間）后拼接SRT格式。

來源：酷虎云字幕識別轉(zhuǎn)換api接口開放平臺