素材庫影片轉碼/審核狀態回調通知

作用

使用者將影片上傳至素材庫後，影片會依序經歷「轉碼 → 審核」兩個非同步處理階段。開啟本回調後，當素材庫影片在轉碼成功/失敗、審核通過/不通過時，伺服器端會向客戶在「回調設定」中配置的介面地址以 POST 方式推送通知，便於客戶感知素材處理進度並做後續處理（典型場景：偽直播選擇素材前，先確認影片已轉碼完成且審核通過）。

回調失敗重試

• 介面如果沒有返回 http status 200 狀態碼，會認為客戶處理本次回調失敗，針對失敗的情況，會重試 3 次 回調。

回調參數說明

• 請求方式: POST
• Content-Type: application/json

說明：簽名 sign 與時間戳 timestamp 隨 BODY 一起提交，不會出現在 URL query 參數中（與本站部分將簽名放在 query 的回調不同，接入時請以 BODY 為準）。

事件類型說明

event 欄位取值如下：

轉碼與審核是兩個獨立階段：若影片需審核，轉碼完成後會先推送 transcode_success，審核完成後再單獨推送 audit_pass / audit_fail。

BODY 參數

簽名規則

為防止回調請求被偽造，請務必校驗 sign 的正確性。

• 簽名拼接方式：sign = encrypt(appSecret + timestamp)
• encrypt 取決於帳號「回調簽名加密方式」設定：
  • 預設為 MD5：sign = MD5(appSecret + timestamp)（32 位小寫）
  • 若設定為 SHA256：sign = SHA256(appSecret + timestamp)
• appSecret 為帳號的開發者金鑰，timestamp 為本次回調 BODY 中的 timestamp。
• 校驗時：取出 BODY 中的 timestamp，用同樣的拼接與加密方式計算本地簽名，與 BODY 中的 sign 比對，一致則為合法請求。

回調資料範例

請求地址範例：https://www.example.com/xxx/callback（sign、timestamp 在下方 BODY 中）

請求體（body 參數：application/json）範例

轉碼成功（transcode_success，成功類事件 remark 為空）

{
  "materialId": "1a2b3c4d5e6f",
  "event": "transcode_success",
  "title": "产品介绍视频.mp4",
  "duration": 62,
  "remark": "",
  "timestamp": "1701964858687",
  "sign": "d5079f2e8ba19e49bfd3d9575866d80f"
}

轉碼失敗（transcode_fail，remark 攜帶失敗原因）

{
  "materialId": "1a2b3c4d5e6f",
  "event": "transcode_fail",
  "title": "产品介绍视频.mp4",
  "duration": 0,
  "remark": "转码失败，请检查视频格式或重新上传",
  "timestamp": "1701964858687",
  "sign": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

審核通過（audit_pass）與轉碼成功結構一致，event 為 audit_pass；審核不通過（audit_fail）與轉碼失敗結構一致，event 為 audit_fail 且 remark 攜帶不通過原因。

如何設定

透過後台設定：

登入帳戶 - 進入【雲直播】 - 點選【開發設定】- 點選【回調設定】- 素材庫影片轉碼/審核狀態回調

注意：提交的介面地址必須要以 http:// 或者 https:// 開頭。

業務說明

• 狀態階段：素材庫影片處理依序為 转码 → 审核。轉碼成功（transcode_success）後影片檔案已生成；若帳號開啟了內容審核，影片還需等待審核結果（audit_pass / audit_fail）。
• 偽直播等可用時機：若用於偽直播選素材等場景，建議以收到 **audit_pass**（審核通過，或帳號免審時為該事件直接通過）作為影片可用的最終依據；僅收到 transcode_success 並不代表已通過審核。
• 回調地址未配置：未在「回調設定」配置本回調地址時，不會推送任何通知（也不會報錯）。