VAS API DocsVAS API Docs
REST API

Speakers

概述

錄音說話者編輯 API，用於多人對話模式下管理說話者。提供三種操作：全域重命名、單句重新指派、語者合併。

V1.4.1 命名統一：以下兩個端點同時提供 tasks 與 recordings 兩條等價路徑（同一 Controller、同一 UUID）：

推薦（V1.4.1 起）Deprecated（V1.6.0 移除）
PATCH /api/v1/tasks/{taskId}/speakers/renamePATCH /api/v1/recordings/{recordingId}/speakers/rename
PATCH /api/v1/tasks/{taskId}/speakers/reassignPATCH /api/v1/recordings/{recordingId}/speakers/reassign
PATCH /api/v1/tasks/{taskId}/speakers/merge—

新整合請使用 tasks 路徑；既有整合可繼續使用 recordings 路徑直到 V1.6.0。taskId 與 recordingId 為同一 UUID。

PATCH /api/v1/tasks/{taskId}/speakers/rename

Deprecated alias：PATCH /api/v1/recordings/{recordingId}/speakers/rename（V1.6.0 移除）

功能說明

將錄音中某個說話者的所有句子統一更名。適用於將系統自動產生的說話者名稱（如 Guest-1）替換為真實姓名。

認證方式

Header：X-API-Key（詳見 認證機制）

請求參數

Path 參數

參數類型必填說明
taskIdstring是任務 ID（UUID）

Body 參數（JSON）

參數類型必填說明
speaker_idstring是原始語者 ID（如 "Guest-1"），可同時接受目前的顯示標籤（speaker_label）做連續改名；最大 100 字元
new_labelstring是新顯示標籤；最大 100 字元，不得含控制字元（\x00-\x1F、\x7F）或換行（會被寫入 transcript blob、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_idstring解析後的原始語者 ID（即使 request 送的是顯示標籤，回應仍是原始 ID）
data.new_labelstring新顯示標籤
data.affected_sidsarray<int>受影響的句子 SID 列表

特有錯誤碼

錯誤碼HTTP 狀態碼說明處理建議
recording_not_found404找不到錄音確認 taskId 正確
recording_unauthorized403無權限操作此錄音確認錄音屬於該使用者
validation_failed422請求驗證失敗確認 speaker_id 與 new_label 皆已提供、未超過 100 字元、new_label 不含控制字元

PATCH /api/v1/tasks/{taskId}/speakers/reassign

Deprecated alias：PATCH /api/v1/recordings/{recordingId}/speakers/reassign（V1.6.0 移除）

功能說明

將特定句子的說話者重新指派為另一個說話者。適用於修正系統自動辨識（Speaker Diarization）的錯誤結果。

認證方式

Header：X-API-Key（詳見 認證機制）

請求參數

Path 參數

參數類型必填說明
taskIdstring是任務 ID（UUID）

Body 參數（JSON）

參數類型必填說明
sidinteger是句子 ID
target_speaker_idstring是目標語者原始 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.sidinteger被修改的句子 ID
data.old_speaker_idstring原始語者 ID
data.new_speaker_idstring重新指派後的原始語者 ID
data.new_speaker_labelstring重新指派後的顯示標籤（套用 speaker_aliases 後；無 alias 時等於 new_speaker_id）

特有錯誤碼

錯誤碼HTTP 狀態碼說明處理建議
recording_not_found404找不到錄音確認 taskId 正確
recording_unauthorized403無權限操作此錄音確認錄音屬於該使用者
validation_failed422請求驗證失敗確認 sid 與 target_speaker_id 皆已提供且格式正確

PATCH /api/v1/tasks/{taskId}/speakers/merge

與 WebSocket merge_speakers action 對齊，提供歷史錄音的合併能力。

功能說明

把 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 參數

參數類型必填說明
taskIdstring是任務 ID（UUID）

Body 參數（JSON）

參數類型必填說明
source_speaker_idstring是被合併的原始語者 ID 或當前顯示標籤（如 Guest-2 或 王經理），最大 100 字元
target_speaker_idstring是合併目標語者的原始 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_idstring被合併的原始語者 ID（已解析回原始 ID，即使請求時送的是顯示標籤）
data.target_speaker_idstring合併目標的原始語者 ID
data.target_speaker_labelstring目標語者顯示標籤（套用 speaker_aliases 後；無 alias 時等於原始 ID）
data.affected_sidsarray<int>受影響的句子 SID 列表

特有錯誤碼

錯誤碼HTTP 狀態碼說明處理建議
merge_speakers_same_id400source 與 target 解析後為相同語者提供不同的語者 ID
speaker_name_empty400source 或 target 為空字串提供有效的語者 ID
speaker_not_found404source 或 target 在該錄音中不存在確認語者 ID 是否正確
recording_not_found404找不到錄音確認 taskId 正確
speaker_diarization_required422該錄音非多人對話模式此功能僅適用 recognition_mode: multi_speaker 錄音
validation_failed422請求驗證失敗確認 source_speaker_id 與 target_speaker_id 皆已提供且不超過 100 字元

注意事項

  • 支援用別名輸入：若已用 rename 改過顯示名（如 Guest-1 改稱「王經理」），merge 時可直接送「王經理」當作 source 或 target，系統會自動反查回原始 ID
  • 別名轉移：若 source 有別名而 target 沒有，merge 後 target 會繼承 source 的別名
  • 整檔重寫 + 樂觀鎖：每次 merge 會更新 revision，併發編輯需處理 transcript_revision_conflict（409）
  • 不可逆：merge 後 source ID 在該錄音內已無對應句子；若需還原需用 reassign 一句一句改回

相關資源

  • 說話者管理 - 說話者重命名、重新指派、合併的完整指南

版本：V1.5.7 最後更新：2026-05-20

Imports

Summary

Copyright © 2026