GET /api/v1/tasks/{id}、/tasks/{id}/events 與 /tasks — 查詢任務狀態、透過 Server-Sent Events 串流接收處理進度、下載結果、列出過往任務。處理中的任務建議每 5–10 秒輪詢一次，或改用事件串流，不必反覆發送請求。

取得任務

GET https://videoupscaler.co/api/v1/tasks/{id}

回傳帶有最新狀態的任務。當任務處於 queued 或 processing 時，每 5–10 秒輪詢一次。影片越長、解析度越高，處理時間就越久。

curl https://videoupscaler.co/api/v1/tasks/0b6f3c1e-8a52-5d1e-9c43-3f1d2e7a9b10 \
  -H "Authorization: Bearer $VIDEOUPSCALER_API_KEY"

{
  "id": "0b6f3c1e-8a52-5d1e-9c43-3f1d2e7a9b10",
  "status": "completed",
  "resolution": "2k",
  "video_url": "https://example.com/clip.mp4",
  "duration_seconds": 12.4,
  "processed_seconds": 12.4,
  "credits_charged": 26,
  "watermark": false,
  "output_url": "https://…/clip_upscaled.mp4",
  "thumbnail_url": "https://…/clip_first_frame.jpg",
  "error": null,
  "created_at": "2026-09-30T08:00:00.000Z",
  "updated_at": "2026-09-30T08:03:41.000Z"
}

任務不存在或屬於其他帳號時，會回傳 404 not_found。

輪詢範例

async function waitForTask(id) {
  while (true) {
    const res = await fetch(`https://videoupscaler.co/api/v1/tasks/${id}`, {
      headers: { Authorization: `Bearer ${process.env.VIDEOUPSCALER_API_KEY}` },
    });
    const task = await res.json();
    if (task.status === 'completed') return task.output_url;
    if (task.status === 'failed') throw new Error(task.error);
    await new Promise((r) => setTimeout(r, 8000));
  }
}

串流接收任務事件

GET https://videoupscaler.co/api/v1/tasks/{id}/events

除了輪詢，你也可以保持一條連線，以 Server-Sent Events 接收任務進度。這個請求會以 302 重新導向到一個已簽章的串流 URL；SSE 用戶端會自動跟隨重新導向（使用 curl 時請加上 -L）。簽章 URL 本身已帶有存取權限，因此不會把你的 API 金鑰傳送給它。

事件	資料	發生時機
`status`	`{"id": "…", "status": "queued"}`	任務正在等待 GPU（`queued`）或執行中（`processing`）。狀態改變時送出。
`completed`	完整的任務	結果已就緒，隨後串流關閉。
`failed`	完整的任務	處理失敗，點數已退還，隨後串流關閉。
`timeout`	`{"id": "…"}`	串流在 10 分鐘後關閉。若任務仍在執行，請重新開啟 `/events`。

completed 與 failed 的資料和 GET /tasks/{id} 的回傳內容完全相同。若任務已經結束才開啟串流，會立即送出對應的事件。

curl -N -L https://videoupscaler.co/api/v1/tasks/TASK_ID/events \
  -H "Authorization: Bearer $VIDEOUPSCALER_API_KEY"

event: status
data: {"id":"0b6f3c1e-…","status":"queued"}

event: status
data: {"id":"0b6f3c1e-…","status":"processing"}

event: completed
data: {"id":"0b6f3c1e-…","status":"completed","output_url":"https://…","…":"…"}

// npm install eventsource
import { EventSource } from 'eventsource';

const events = new EventSource(`https://videoupscaler.co/api/v1/tasks/${taskId}/events`, {
  fetch: (url, init) =>
    fetch(url, {
      ...init,
      headers: { ...init.headers, Authorization: `Bearer ${process.env.VIDEOUPSCALER_API_KEY}` },
    }),
});
events.addEventListener('status', (e) => console.log(JSON.parse(e.data).status));
events.addEventListener('completed', (e) => {
  console.log('done:', JSON.parse(e.data).output_url);
  events.close();
});
events.addEventListener('failed', (e) => {
  console.error(JSON.parse(e.data).error);
  events.close();
});

# pip install httpx httpx-sse
import json, os, httpx
from httpx_sse import connect_sse

headers = {"Authorization": f"Bearer {os.environ['VIDEOUPSCALER_API_KEY']}"}
url = f"https://videoupscaler.co/api/v1/tasks/{task_id}/events"
with httpx.Client(follow_redirects=True, timeout=None) as client:
    with connect_sse(client, "GET", url, headers=headers) as source:
        for event in source.iter_sse():
            task = json.loads(event.data)
            print(event.event, task["status"])
            if event.event in ("completed", "failed", "timeout"):
                break

輪詢 GET /tasks/{id} 也能得到相同結果，依你的程式架構選擇適合的方式即可。

列出任務

GET https://videoupscaler.co/api/v1/tasks?limit=20&page=1

查詢參數	預設值	說明
`limit`	`20`	每頁任務數，1–100
`page`	`1`	頁碼，從 1 開始

依建立時間由新到舊回傳任務。清單也包含你在網站上建立的任務。

{
  "data": [{ "id": "…", "status": "completed", "…": "…" }],
  "page": 1,
  "limit": 20,
  "total": 42,
  "has_more": true
}

任務物件

欄位	型別	說明
`id`	string	任務 ID
`status`	string	`queued`、`processing`、`completed` 或 `failed`
`resolution`	string	`1080p`、`2k` 或 `4k`
`video_url`	string	你送出的影片
`duration_seconds`	number	輸入影片的長度，從檔案讀取
`processed_seconds`	number	實際提升畫質的秒數。API 任務一律等於 `duration_seconds`；只有帳號仍為免費時在網站上建立的任務才會比較短。
`credits_charged`	integer	此任務扣除的點數（失敗時會退還）
`watermark`	boolean	結果是否帶有浮水印。API 任務一律為 `false`；只有帳號仍為免費時在網站上建立的任務才會是 `true`。
`output_url`	string \| null	`completed` 後的畫質提升影片
`thumbnail_url`	string \| null	`completed` 後結果影片的第一格畫面
`error`	string \| null	`failed` 時的失敗原因
`created_at`	string	ISO 8601 時間
`updated_at`	string	ISO 8601 時間

任務完成後請盡快下載 output_url 並自行保存一份，不要把它當成永久儲存空間。

任務

取得任務

輪詢範例

串流接收任務事件

列出任務

任務物件

On this page