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로 받을 수 있습니다. 이 요청은 서명된 스트림 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–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