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을 다운로드해 사본을 직접 보관하세요. 영구 저장소로 의존하지 마세요.

작업 조회

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

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`를 다시 여세요.

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