建立畫質提升任務
POST /api/v1/upscale — 為影片扣除點數，並開始將它提升到 1080p、2K 或 4K。支援長度最多 600 秒的 MP4、MOV 與 WebM 檔案，影片長度由伺服器直接從檔案讀取後計費，建議每次請求都附上 Idempotency-Key，重試時不會重複扣點。
POST https://videoupscaler.co/api/v1/upscale開始一次畫質提升，並回傳新建立的任務。我們會先下載影片、從檔案讀出實際長度，並在處理開始前扣除對應的點數。你不需要自行傳入影片長度。
請求
標頭
| 標頭 | 必填 | 說明 |
|---|---|---|
Authorization | 是 | Bearer <your API key> |
Content-Type | 是 | application/json |
Idempotency-Key | 建議 | 任意 1–255 個可列印 ASCII 字元組成的字串。用相同的 Key 重試絕不會重複扣點。請參閱冪等性。 |
請求本文
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
video_url | string | 是 | 影片的公開 http(s) URL，或 /uploads 回傳的 video_url。 |
resolution | string | 是 | 1080p、2k 或 4k。 |
影片要求
- 格式：MP4、MOV 與 WebM。
- 長度：1080p 最長 1200 秒，2k 與 4k 最長 600 秒。
- 大小：遠端
video_url最大 500MB，透過 /uploads 上傳則最大 100MB。 video_url所在的伺服器必須能對一般的GET請求直接回傳檔案，並附上Content-Length標頭。S3、R2 或 Google Cloud Storage 的簽章連結都可以使用；YouTube 或 Google Drive 預覽這類分享頁面則不行。- 沒有總長度資訊的 Fragmented MP4 檔案會被拒絕，請先重新編碼成一般的 MP4。
- WebM 檔案的檔頭必須包含影片長度。瀏覽器錄製（MediaRecorder）的檔案通常沒有，請先重新編碼。
範例
curl https://videoupscaler.co/api/v1/upscale \
-H "Authorization: Bearer $VIDEOUPSCALER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1234" \
-d '{"video_url": "https://example.com/clip.mp4", "resolution": "2k"}'const res = await fetch('https://videoupscaler.co/api/v1/upscale', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VIDEOUPSCALER_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'order-1234',
},
body: JSON.stringify({ video_url: 'https://example.com/clip.mp4', resolution: '2k' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const task = await res.json();res = requests.post(
"https://videoupscaler.co/api/v1/upscale",
headers={
"Authorization": f"Bearer {os.environ['VIDEOUPSCALER_API_KEY']}",
"Idempotency-Key": "order-1234",
},
json={"video_url": "https://example.com/clip.mp4", "resolution": "2k"},
timeout=300,
)
res.raise_for_status()
task = res.json()回應
回傳 201 Created 與任務物件：
{
"id": "0b6f3c1e-8a52-5d1e-9c43-3f1d2e7a9b10",
"status": "processing",
"resolution": "2k",
"video_url": "https://example.com/clip.mp4",
"duration_seconds": 12.4,
"processed_seconds": 12.4,
"credits_charged": 26,
"watermark": false,
"output_url": null,
"thumbnail_url": null,
"error": null,
"created_at": "2026-09-30T08:00:00.000Z",
"updated_at": "2026-09-30T08:00:02.000Z"
}接著輪詢任務直到狀態變成 completed。
這個請求會先下載影片才回應，因此遠端檔案較大時可能需要一段時間。逾時時間請至少設為 5 分鐘。
冪等性
每個請求都帶上 Idempotency-Key，並在逾時或網路錯誤後重試時沿用同一個值：
- 相同的 Key 搭配相同的
video_url與resolution，會以200 OK回傳原本的任務，不會再次扣點。 - 相同的 Key 搭配不同的
video_url或resolution，會回傳409 idempotency_conflict。 - 不帶這個標頭時，每個請求都會建立新任務並各自扣點。
計費
價格 = 影片長度（以整秒計，無條件進位）× 該解析度的費率，詳見點數與價格。一支 12.4 秒的影片以 2K 處理，需要 13 × 2 = 26 點數。
若任務失敗，點數會自動退還，任務狀態變為 failed。
錯誤
| 狀態碼 | 錯誤碼 | 發生時機 |
|---|---|---|
400 | invalid_request | video_url、resolution 或 Idempotency-Key 缺少或無效 |
401 | unauthorized | 缺少 API 金鑰 或 Key 無效 |
403 | paid_plan_required | 帳號從未購買點數或訂閱 |
402 | insufficient_credits | 你的點數餘額不足以處理這支影片 |
409 | idempotency_conflict | 這個 Idempotency-Key 已搭配不同參數使用過 |
413 | file_too_large | 影片超過 500MB |
422 | video_fetch_failed | 我們無法下載 video_url |
422 | unsupported_video | 不是可讀取的 MP4、MOV 或 WebM，或缺少長度資訊 |
422 | video_too_long | 影片長度超過該解析度的上限（1080p 為 1200 秒，2k 與 4k 為 600 秒） |
422 | video_not_found | 上傳用的 video_url 找不到檔案（上傳未完成） |
504 | upstream_timeout | 下載 video_url 超過 4 分鐘 |
錯誤格式請參閱錯誤。