截屏換封面
更新時間 2025-04-16 10:39:52
最近更新時間: 2025-04-16 10:39:52
分享文章
通過本接口對媒體庫的視頻文件進行截屏并設置為封面。
接口功能介紹
用戶可通過本接口對媒體庫的視頻文件進行截屏并設置為封面。
接口約束
本接口的單用戶QPS限制為20次/秒。超過限制，API調用會被限流，這可能會影響您的業務，請合理調用。
URI
POST /task/extractFrame
請求體body參數
| 參數 | 是否必填 | 參數類型 | 說明 | 示例 | 下級對象 |
|---|---|---|---|---|---|
| videoId | 是 | String | 視頻ID。 | 34c71dba-f280-4f5e-a05f-f4daed837fef | |
| time | 否 | Integer | 可選參數，為截屏的時間，如不填，默認使用智能截圖，在前100幀內挑選一張最合適的圖片作為封面，如傳入小數則會自動四舍五入。 | 0 | |
| quality | 否 | Integer | 可選參數，圖片質量，1 ~ 31，1表示質量最好，31 質量最差，默認為 2。 | 2 | |
| width | 否 | Integer | 可選參數，寬以及高，可傳入其中一個，剩下的會根據源視頻進行等比例縮放。 | 1024 | |
| height | 否 | Integer | 可選參數，寬以及高，可傳入其中一個，剩下的會根據源視頻進行等比例縮放。 | 768 | |
| useDefaultWatermarkTemplate | 否 | Boolean | 可選參數，是否使用水印默認模板，如果不填寫默認為 false。 | true | |
| watermarkTemplate | 否 | Long | 可選參數，當 userDefaultWatermarkTemplate 為 true 時無效。當 userDefaultWatermarkTemplate 為 false 或者不傳入，watermarkTemplate 也不傳入時表示不使用水印。 | 100000000003 |
響應參數
| 參數 | 是否必填 | 參數類型 | 說明 | 示例 | 下級對象 |
|---|---|---|---|---|---|
| code | 是 | Integer | 本次請求的結果碼。 | 0 | |
| message | 是 | String | 錯誤文本信息，創建成功時，為空字符串。 | "" | |
| data | 是 | Object | 返回數據。 | data |
表 data
| 參數 | 是否必填 | 參數類型 | 說明 | 示例 | 下級對象 |
|---|---|---|---|---|---|
| coverUrl | 是 | String | 新封面訪問地址 | //example.gdoss.xstore.daliqc.cn/a4ea36031c3046f7a01742f3fda4e249.jpg |
請求示例
請求體body
{
"videoId": "34c71dba-f280-4f5e-a05f-f4daed837fef",
"time": 0,
"quality": 2,
"width": 1024,
"height": 768,
"useDefaultWatermarkTemplate": true,
"watermarkTemplate": 100000000003
}
響應示例
{
"code": 0,
"message": "",
"data":{
"coverUrl":"//example.gdoss.xstore.daliqc.cn/a4ea36031c3046f7a01742f3fda4e249.jpg"
}
}
狀態碼
| Http 狀態碼 | 狀態碼信息 | 狀態碼描述 |
|---|---|---|
| 0 | 表示業務成功 | 表示業務成功 |
| 400 | 請求參數有誤 | 請求參數有誤 |
| 403 | 用戶鑒權失敗，用戶無操作權限 | 用戶鑒權失敗，用戶無操作權限 |
| 404 | 請求的資源不存在，輸入錯誤的URL | 請求的資源不存在，輸入錯誤的URL |
| 500 | 業務執行異常 | 業務執行異常 |
錯誤碼
OpenAPI錯誤碼請參考 錯誤碼說明。
