API 串接

您的第一份轉錄

轉錄會在背景進行。建立工作後會立即回應；請持續查詢狀態，直到結果就緒。

1. 1

   建立工作

   使用 POST /transcripts 傳送可直接公開存取的媒體網址。請保留回傳的 id。

2. 2

   查詢進度

   每隔 15–30 秒輪詢 GET /transcripts/{id}，直到 status 為 complete 或 error。

3. 3

   使用轉錄結果

   從 data 讀取 JSON；若請求 SRT 或 VTT，則透過 export_url 下載檔案。

工作狀態

其他狀態均視為處理中。未來可能新增中間狀態。

身分驗證

每次請求時，請在 Authorization 標頭中傳送 API 金鑰，內容須與建立時顯示的完全相同。

Authorization: <your api key>

請勿加上 Bearer 前綴。

新金鑰以 tp_live_ 開頭。完整金鑰僅在建立時顯示一次。若遺失，請撤銷該金鑰並建立新的金鑰；已撤銷的金鑰會立即失效。

需要有效訂閱及具備所需權限的 API 金鑰。

建立轉錄

為公開網址上的媒體檔案建立轉錄工作。工作加入佇列後即回應，狀態為 status: "initializing"。

Taption 會直接下載檔案。Google Drive 或 Dropbox 預覽頁等分享頁面連結無法使用。

media_urlstring必填

媒體檔案的直接下載連結。

最多 2048 個字元

extensionstring必填

媒體檔案格式。

mp3wavm4aaacflacwmaopusmp4

languagestring必填

以語言標籤指定媒體使用的語言。請參閱語言參考資料。

查看語言標籤

namestring

轉錄的顯示名稱。預設為 `media_url` 中的檔名。較長的名稱會截短至 200 個字元。

最多 200 個字元

export_typestring

輸出格式。預設為 json，會在 data 中回傳已解析的轉錄內容。srt 和 vtt 則在 export_url 中回傳檔案連結。

jsonsrtvtt

預設值：json

max_charinteger

每段字幕的字元上限。中文、日文、韓文及粵語預設為 `16`，其他語言為 `65`。超出 1-200 的值會被忽略，改用預設值。

1–200

回應

取得轉錄

取得轉錄的目前狀態及結果。工作進行時，請每隔 15–30 秒輪詢一次。

若格式為 json 或未指定匯出類型，完成的結果會顯示在 data 中。若為 srt 或 vtt，請透過 export_url 下載檔案。

idstring必填

由 POST /transcripts 回傳的轉錄 ID。最多 256 個字元

回應

轉錄物件

建立工作及查詢狀態的請求會回傳 JSON 物件。其欄位描述工作資訊，以及就緒後的輸出結果。

idstring

轉錄 ID，搭配 `GET /transcripts/{id}` 使用。

statusstring

工作的目前狀態：`initializing`、`transcribing`、`complete` 或 `error`。其他值均視為處理中。

dataJSON

當 json 或省略 export_type 的結果就緒時，提供已解析的 JSON 匯出內容；否則為空字串。

export_urlstring

srt 或 vtt 匯出檔的下載連結，就緒前為空。若格式為 json 或省略 export_type，狀態回應會省略此欄位。

messagestring

目前狀態的補充資訊。在 `transcribing` 期間，可能為 `ANALYZING` 或 `FINALIZING` 等進度階段。當 `status` 為 `error` 時，描述失敗原因。此內容供人閱讀，請勿用程式解析。

error_codestring

選用的機器可讀代碼，表示提交限制錯誤。

limitinteger

此次適用的帳戶上限，於 HTTP 429 回應中提供。

錯誤與重試

請依 HTTP 狀態碼決定下一步。message 欄位供人閱讀，措辭可能變動。

API 回應包含 X-Request-Id 標頭。就某個請求聯絡客服時，請提供此值。