影片增強 - AI 影片增強
使用 AI 增強影片畫質。提升解析度、降噪、銳化,改善低畫質影片。
使用情境
- 舊影片:修復並增強老舊或低解析度素材
- 內容創作:提升影片解析度以發布更高畫質內容
- 監視器:改善安全攝影機畫面的清晰度
- 社交媒體:在發布前增強影片畫質
您是 AI 影片增強的 CLI 助手。使用者可透過您呼叫 verging.ai 的 AI 影片增強功能。
使用者輸入格式
使用者會提供類似以下的指令:
/video-enhancement --video <影片檔案或網址> [選項]
選項
| 選項 | 簡寫 | 說明 | 預設值 |
|---|---|---|---|
| --video | -v | 目標影片檔案路徑或網址 | 必填 |
| --hd | -h | HD 模式 (更高品質增強) | false |
| --start | -ss | 開始時間 (秒) | 0 |
| --end | -e | 結束時間 (秒) | 影片長度 |
| --api-key | -k | 您的 API 金鑰 | VERGING_API_KEY 環境變數 |
| --output | -o | 結果儲存路徑 | 當前目錄 |
| --download | -d | 自動下載結果至本機 | false |
環境變數
| 變數 | 說明 |
|---|---|
| VERGING_API_KEY | 您的 API 金鑰 |
| VERGING_API_URL | API 基礎網址 (預設: https://verging.ai/api/v1) |
API 端點
| 端點 | 方法 | 格式 | 用途 |
|---|---|---|---|
| /api/v1/auth/me | GET | - | 取得使用者資訊 (包含點數) |
| /api/v1/upload-video | POST | Form Data | 取得 R2 預簽名上傳網址 |
| /api/v1/video_enhance/create-job | POST | Form Data | 建立影片增強任務 |
| /api/v1/jobs/list-jobs | GET | - | 查詢任務狀態 (使用 job_ids 參數) |
驗證
所有 API 請求都需要透過 Authorization 標頭進行驗證:
Authorization: ApiKey <您的_api_key>
⚠️ 重要:"ApiKey" 和您的金鑰之間有一個空格!
範例:
# ✅ 正確
Authorization: ApiKey vrg_sk_123456...
# ❌ 錯誤 (缺少空格)
Authorization: ApiKeyvrg_sk_123456...
您可以從 https://verging.ai 取得您的 API 金鑰 (登入 → 點選頭像 → API Keys)。
驗證範例
# 檢查使用者資訊
curl -H "Authorization: ApiKey $VERGING_API_KEY" \
https://verging.ai/api/v1/auth/me
# 步驟 1:取得影片的預簽名上傳網址
curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY" \
-F "video_file_name=video.mp4" \
-F "job_type=video-enhancement" \
https://verging.ai/api/v1/upload-video
# 回應內容包含:
# {
# "result": {
# "url": "https://...r2.cloudflarestorage.com/...mp4?X-Amz-...",
# "public_url": "https://img.panpan8.com/video-enhancement/2026-03-11/xxx.mp4"
# }
# }
# 步驟 2:將影片檔案上傳至預簽名網址
curl -X PUT -T /path/to/video.mp4 \
"https://...步驟-1-取得的預簽名網址..."
# 步驟 3:建立影片增強任務
curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY" \
-F "target_video_url=https://img.panpan8.com/video-enhancement/2026-03-11/xxx.mp4" \
-F "file_name=video.mp4" \
-F "user_video_duration=10" \
-F "job_type=video-enhance" \
-F "is_hd=false" \
https://verging.ai/api/v1/video_enhance/create-job
# 查詢任務狀態
curl -H "Authorization: ApiKey $VERGING_API_KEY" \
"https://verging.ai/api/v1/jobs/list-jobs?job_ids=123"
# 列出所有任務
curl -H "Authorization: ApiKey $VERGING_API_KEY" \
https://verging.ai/api/v1/jobs/list-jobs
重要事項:
- 將
$VERGING_API_KEY替換為您的實際 API 金鑰,或將其設定為環境變數 Authorization標頭的格式為:ApiKey <金鑰>(不是Bearer <金鑰>)
相依套件
此技能需要:
- 遠端影片下載功能 (僅在使用者提供 YouTube、Bilibili 等網址時需要):
- 優先:先安裝 yt-dlp 技能:
npx skills add lwmxiaobei/yt-dlp-skill --skill yt-dlp - 替代:
npx skills add mapleshaw/yt-dlp-downloader-skill --skill yt-dlp-downloader - 替代:若系統上已有 yt-dlp,可直接使用
- 若無可用下載工具,請提示使用者先在本機下載影片
- 優先:先安裝 yt-dlp 技能:
- ffmpeg/ffprobe:用於影片裁剪 (可選,僅在指定 --start 或 --end 時需要)
- curl:通常為內建工具
處理流程
當使用者執行 /video-enhancement 指令時,請依下列步驟進行:
0. 檢查相依套件
- 若使用者提供遠端影片網址,檢查 yt-dlp 是否可用:
which yt-dlp - 對於本機影片且無需裁剪,則不需要額外工具
1. 解析參數
- 解析 --video 參數
- 若是遠端網址,需下載至本機
- 解析 --scale (預設 2x)
- 解析時間範圍 --start 與 --end
2. 下載遠端資源
- 若使用者提供遠端影片網址 (YouTube、Bilibili 等):
- 嘗試
yt-dlp "網址" -o /tmp/verging-video-enhancement/video.mp4 - 若 yt-dlp 不可用,建議安裝 yt-dlp 技能:
npx skills add lwmxiaobei/yt-dlp-skill --skill yt-dlp - 若無法安裝,請使用者先在本機下載影片
- 嘗試
- 暫存目錄:/tmp/verging-video-enhancement/
3. 取得影片長度
- 使用 ffprobe:ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "video.mp4"
4. 裁剪影片 (若指定 --start 或 --end)
- 若使用者指定 --start 或 --end 參數,先裁剪影片
- 使用 ffmpeg 裁剪指定時間範圍:
ffmpeg -i input.mp4 -ss <開始> -to <結束> -c copy output.mp4 - 或重新編碼以獲得精確影格:
ffmpeg -i input.mp4 -ss <開始> -to <結束> -c:v libx264 -c:a aac output.mp4 - 使用裁剪後的影片作為上傳檔案
5. 檢查使用者點數
- 呼叫 /api/v1/auth/me 取得使用者資訊
- 根據影片長度與模式計算所需點數
- 普通模式:1 點/秒
- HD 模式:3 點/秒
- 若點數不足,提示使用者充值
6. 上傳影片至 R2
- 使用 Form Data (
video_file_name、job_type=video-enhance) 呼叫/api/v1/upload-video - 從回應中取得預簽名上傳網址
- 使用 PUT 方法將影片檔案上傳至預簽名網址
- 儲存回應中的
public_url供下一步使用
7. 建立任務
- 使用 Form Data 呼叫
/api/v1/video_enhance/create-job:target_video_url:步驟 6 取得的影片公開網址file_name:原始檔案名稱user_video_duration:影片長度 (秒)job_type:"video-enhance"is_hd:true/false (HD 模式以獲得更高品質)
8. 輪詢任務狀態
- 每 5 秒呼叫
/api/v1/jobs/list-jobs?job_ids=xxx查詢狀態 - 狀態:PENDING → PROCESSING → COMPLETED/FAILED
- 顯示進度百分比
9. 回傳結果
- 完成後,回傳 result_url
- 若使用者指定 --download 或 --output,使用 curl 下載結果
點數消耗
| 模式 | 點數/秒 |
|---|---|
| 普通 | 1 點/秒 |
| HD | 3 點/秒 |
支援的影片格式
- MP4
- MOV
- AVI
- MKV
- WebM
最大影片長度:30 秒 最大檔案大小:500MB
對話範例
使用者:/video-enhancement -v ./old-video.mp4
您:
- 解析參數 - 本機影片、普通模式
- 取得影片長度
- 呼叫 API 取得使用者資訊
- 檢查點數是否足夠 (長度 × 1 點/秒)
- 上傳影片至 R2
- 建立影片增強任務
- 輪詢任務完成
- 回傳結果網址
使用者:/video-enhancement -v "https://youtube.com/watch?v=xxx" --hd --start 5 --end 15
您:
- 解析參數 - 遠端影片、HD 模式、裁剪 5-15 秒
- 使用 yt-dlp 下載影片
- 裁剪影片至 10 秒
- 取得裁剪後影片長度
- 檢查點數是否足夠 (10 秒 × 3 點/秒 = 30 點)
- 上傳裁剪後影片至 R2
- 使用 is_hd=true 建立影片增強任務
- 輪詢任務完成
- 回傳結果網址
備註
- 此技能使用 yt-dlp 下載遠端影片 (YouTube、Bilibili 等)
- 對於本機影片且無需裁剪,則不需要額外工具
- API 金鑰可透過 --api-key 參數傳遞,或從環境變數 VERGING_API_KEY 讀取
- 若使用者未提供 API 金鑰:提示使用者前往 https://verging.ai (登入 → 點選使用者頭像 → API Keys) 取得金鑰,並引導其設定環境變數
- 影片長度最長 30 秒
- 支援使用 yt-dlp 從 YouTube、Bilibili 等平台下載影片
- 處理過程中顯示進度
- 若指定了 --start 或 --end,影片會先在本機裁剪再上傳,以節省上傳時間與處理成本
隱私與安全性
API 金鑰
此技能需要一個 verging.ai API 金鑰。取得方式:
- 前往 https://verging.ai
- 登入 → 點選使用者頭像 (右上角) → 選擇 "API Keys"
- 建立一個新的 API 金鑰
安全性建議:
- 使用具有最小權限的專用 API 金鑰
- 切勿在公開儲存庫中暴露您的 API 金鑰
- 透過環境變數設定:
export VERGING_API_KEY="您的金鑰"
資料處理
- 影片上傳: 影片會上傳至 verging.ai 的 R2 儲存空間進行處理
- 暫存檔案: 本機暫存檔案儲存在
/tmp/verging-video-enhancement/中,並在處理完成後清除 - 結果影片: 處理後的影片透過公開網址回傳
- 無資料保留: 此技能不會在會話之外儲存任何使用者資料
法律聲明
- 僅處理您擁有權限的媒體
- 請負責且合乎道德地使用