GET /api/v1/tasks/{id}、/tasks/{id}/events 和 /tasks — 查询任务状态、订阅处理进度、下载结果、列出历史任务。

查询任务

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 并自行保存一份，不要把它当作永久存储。

查询任务

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

事件	数据	触发时机
`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

任务

查询任务

轮询示例

订阅任务事件流

列出任务

任务对象

On this page