POST /api/v1/upscale — 為影片扣除點數，並開始將它提升到 1080p、2K 或 4K。

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。
長度：最長 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`	影片長度超過 600 秒
`422`	`video_not_found`	上傳用的 `video_url` 找不到檔案（上傳未完成）
`504`	`upstream_timeout`	下載 `video_url` 超過 4 分鐘

錯誤格式請參閱錯誤。

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。
長度：最長 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`	影片長度超過 600 秒
`422`	`video_not_found`	上傳用的 `video_url` 找不到檔案（上傳未完成）
`504`	`upstream_timeout`	下載 `video_url` 超過 4 分鐘

錯誤格式請參閱錯誤。

建立畫質提升任務

請求

標頭

請求本文

影片要求

範例

回應

冪等性

計費

錯誤

On this page

建立畫質提升任務

請求

標頭

請求本文

影片要求

範例

回應

冪等性

計費

錯誤

On this page