GET /api/v1/tasks/{id}、/tasks/{id}/events、/tasks — タスクのステータス確認、Server-Sent Events による進行状況のストリーミング、結果のダウンロード、過去のタスクの一覧表示を行います。

タスクを取得する

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

ポーリングの代わりに、1 本の接続を開いたままにして、タスクの進行状況を Server-Sent Events として受け取ることもできます。このリクエストは署名付きストリーム URL への 302 リダイレクトを返します。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 ページあたりのタスク数（1〜100）
`page`	`1`	ページ番号（1 から開始）

タスクを新しい順に返します。Web サイトで作成したタスクも一覧に含まれます。

{
  "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` と同じです。短くなるのは、アカウントが無料だった間に Web サイトで作成されたタスクのみです。
`credits_charged`	integer	このタスクで差し引かれたクレジット（失敗した場合は返還）
`watermark`	boolean	結果に透かしが入っているかどうか。API タスクでは常に `false` です。`true` になるのは、アカウントが無料だった間に Web サイトで作成されたタスクのみです。
`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