REST API
說話者 API
概述
錄音說話者編輯 API，用於多人對話模式下管理說話者。提供三種操作：全域重命名、單句重新指派、語者合併。
所有端點皆以
/api/v1/tasks/{taskId}/speakers/...為唯一正式路徑。
PATCH /api/v1/tasks/{taskId}/speakers/rename
功能說明
將錄音中某個說話者的所有句子統一更名。適用於將系統自動產生的說話者名稱（如 Guest-1）替換為真實姓名。
認證方式
Header：X-API-Key（詳見 認證機制）
請求參數
Path 參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
taskId | string | 是 | 任務 ID（UUID） |
Body 參數（JSON）
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
speaker_id | string | 是 | 原始語者 ID（如 "Guest-1"），可同時接受目前的顯示標籤（speaker_label）做連續改名；最大 100 字元 |
new_label | string | 是 | 新顯示標籤；最大 100 字元，不得含控制字元（\x00-\x1F、\x7F）或換行（會被寫入逐字稿、SSE 事件、TXT/SRT/CSV 匯出檔） |
請求範例
curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/rec_abc123/speakers/rename" \
-H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
-H "Content-Type: application/json" \
-d '{
"speaker_id": "Guest-1",
"new_label": "王經理"
}'
成功回應
HTTP 200
{
"data": {
"speaker_id": "Guest-1",
"new_label": "王經理",
"affected_sids": [1, 3, 5]
}
}
回應欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
data.speaker_id | string | 解析後的原始語者 ID（即使 request 送的是顯示標籤，回應仍是原始 ID） |
data.new_label | string | 新顯示標籤 |
data.affected_sids | array<int> | 受影響的句子 SID 列表 |
特有錯誤碼
| 錯誤碼 | HTTP 狀態碼 | 說明 | 處理建議 |
|---|---|---|---|
recording_not_found | 404 | 找不到錄音 | 確認 taskId 正確 |
validation_failed | 422 | 請求驗證失敗 | 確認 speaker_id 與 new_label 皆已提供、未超過 100 字元、new_label 不含控制字元 |
speaker_transcript_not_found | 404 | 找不到逐字稿 | 確認錄音已完成轉錄 |
speaker_diarization_required | 422 | 此功能僅支援語者分離錄音 | 僅適用於多人辨識模式的錄音 |
speaker_name_empty | 422 | new_label 為空 | 提供有效的 new_label |
speaker_name_duplicate | 422 | 該名稱已被其他語者使用（含其他語者目前的顯示名稱與原始語者 ID），或輸入的顯示名稱同時對應到多個語者 | 改用不重複的名稱；輸入有歧義時改用原始語者 ID |
speaker_not_found | 422 | 找不到指定的語者 | 確認 speaker_id 存在 |
transcript_revision_conflict | 409 | 同一份逐字稿正有其他寫入在進行 | 稍後重試即可；本次變更未生效 |
storage_upload_failed | 500 | 逐字稿寫回儲存服務失敗 | 稍後重試；本次變更未生效 |
PATCH /api/v1/tasks/{taskId}/speakers/reassign
功能說明
將特定句子的說話者重新指派為另一個說話者。適用於修正系統自動辨識（Speaker Diarization）的錯誤結果。
認證方式
Header：X-API-Key（詳見 認證機制）
請求參數
Path 參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
taskId | string | 是 | 任務 ID（UUID） |
Body 參數（JSON）
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
sid | integer | 是 | 句子 ID |
target_speaker_id | string | 是 | 目標語者原始 ID（取自 init_sentence.speaker_id；reassign 不接受顯示標籤，必須送原始 ID）；最大 100 字元 |
請求範例
curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/rec_abc123/speakers/reassign" \
-H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
-H "Content-Type: application/json" \
-d '{
"sid": 3,
"target_speaker_id": "Guest-2"
}'
成功回應
HTTP 200
{
"data": {
"sid": 3,
"old_speaker_id": "Guest-1",
"new_speaker_id": "Guest-2",
"new_speaker_label": "李總監"
}
}
回應欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
data.sid | integer | 被修改的句子 ID |
data.old_speaker_id | string | 原始語者 ID |
data.new_speaker_id | string | 重新指派後的原始語者 ID |
data.new_speaker_label | string | 重新指派後的顯示標籤（套用 speaker_aliases 後；無 alias 時等於 new_speaker_id） |
特有錯誤碼
| 錯誤碼 | HTTP 狀態碼 | 說明 | 處理建議 |
|---|---|---|---|
recording_not_found | 404 | 找不到錄音 | 確認 taskId 正確 |
validation_failed | 422 | 請求驗證失敗 | 確認 sid 與 target_speaker_id 皆已提供且格式正確 |
speaker_transcript_not_found | 404 | 找不到逐字稿 | 確認錄音已完成轉錄 |
speaker_op_not_allowed_multi_channel | 422 | 多聲道錄音不支援此語者操作（details.recognition_mode 帶辨識模式） | 多聲道的語者由聲道決定，請改用聲道設定 |
speaker_diarization_required | 422 | 此功能僅支援語者分離錄音 | 僅適用於多人辨識模式的錄音 |
speaker_sid_not_found | 422 | 找不到指定的句子 | 確認 sid 存在於該錄音 |
speaker_not_found | 422 | 找不到指定的語者 | 確認 target_speaker_id 存在 |
transcript_revision_conflict | 409 | 同一份逐字稿正有其他寫入在進行 | 稍後重試即可；本次變更未生效 |
storage_upload_failed | 500 | 逐字稿寫回儲存服務失敗 | 稍後重試；本次變更未生效 |
PATCH /api/v1/tasks/{taskId}/speakers/merge
與 WebSocket
merge_speakersaction 對齊，提供歷史錄音的合併能力。
功能說明
把 source 語者的所有句子歸屬到 target 語者；source 的別名（若有）會轉移到 target（若 target 尚無別名）。適用於語者分離模型把同一人誤判為兩個 speaker 的情境（如 Guest-1 + Guest-2 其實是同一人）。
vs. reassign：
reassign只改單句；merge改該語者所有句子。 vs. rename：rename只改顯示名稱（alias），不動 speaker ID；merge把多個 speaker 整併為一個。
認證方式
Header：X-API-Key（詳見 認證機制）
請求參數
Path 參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
taskId | string | 是 | 任務 ID（UUID） |
Body 參數（JSON）
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
source_speaker_id | string | 是 | 被合併的原始語者 ID 或當前顯示標籤（如 Guest-2 或 王經理），最大 100 字元 |
target_speaker_id | string | 是 | 合併目標語者的原始 ID 或當前顯示標籤（如 Guest-1），最大 100 字元 |
請求範例
curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/rec_abc123/speakers/merge" \
-H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
-H "Content-Type: application/json" \
-d '{
"source_speaker_id": "Guest-2",
"target_speaker_id": "Guest-1"
}'
成功回應
HTTP 200
{
"data": {
"source_speaker_id": "Guest-2",
"target_speaker_id": "Guest-1",
"target_speaker_label": "王經理",
"affected_sids": [3, 5, 7]
}
}
回應欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
data.source_speaker_id | string | 被合併的原始語者 ID（已解析回原始 ID，即使請求時送的是顯示標籤） |
data.target_speaker_id | string | 合併目標的原始語者 ID |
data.target_speaker_label | string | 目標語者顯示標籤（套用 speaker_aliases 後；無 alias 時等於原始 ID） |
data.affected_sids | array<int> | 受影響的句子 SID 列表：原屬來源語者的句子，加上顯示名稱因合併而改變的目標語者原有句子（例如來源語者的自訂名稱轉給目標語者時） |
特有錯誤碼
| 錯誤碼 | HTTP 狀態碼 | 說明 | 處理建議 |
|---|---|---|---|
merge_speakers_same_id | 400 | source 與 target 解析後為相同語者 | 提供不同的語者 ID |
speaker_name_empty | 422 | source 或 target 為空字串 | 提供有效的語者 ID |
speaker_not_found | 422 | source 或 target 在該錄音中不存在 | 確認語者 ID 是否正確 |
recording_not_found | 404 | 找不到錄音 | 確認 taskId 正確 |
speaker_diarization_required | 422 | 該錄音非多人對話模式 | 此功能僅適用 recognition_mode: multi_speaker 錄音 |
validation_failed | 422 | 請求驗證失敗 | 確認 source_speaker_id 與 target_speaker_id 皆已提供且不超過 100 字元 |
transcript_revision_conflict | 409 | 同一份逐字稿正有其他寫入在進行 | 稍後重試即可；本次變更未生效 |
storage_upload_failed | 500 | 逐字稿寫回儲存服務失敗 | 稍後重試；本次變更未生效 |
注意事項
- 支援用顯示名稱輸入：改過名的語者（如 Guest-1 改稱「王經理」）可直接送「王經理」當作 source 或 target，系統會自動反查回原始 ID。多聲道錄音各路由建立時帶入的顯示名稱同樣可以直接輸入
- 別名轉移：若 source 有別名而 target 沒有，merge 後 target 會繼承 source 的別名；target 原有的句子也會一併改用這個名稱，並列入
affected_sids - 併發保護：每次 merge 會更新
revision。本端點沒有expected_revision參數；同一份逐字稿正有其他變更在進行時會回transcript_revision_conflict（409），稍後重試即可 - 不可逆：merge 後 source ID 在該錄音內已無對應句子；若需還原需用
reassign一句一句改回
相關資源
- 說話者管理 - 說話者重命名、重新指派、合併的完整指南
版本：V1.24.1 最後更新：2026-09-28