POST /api/v1/upscale — 동영상에 대한 크레딧을 차감하고 1080p, 2K 또는 4K로 업스케일을 시작합니다.

POST https://videoupscaler.co/api/v1/upscale

업스케일을 시작하고 새 작업을 반환합니다. 작업이 시작되기 전에 동영상을 다운로드하고, 파일에서 실제 길이를 읽어 그에 해당하는 크레딧을 차감합니다. 길이를 직접 보낼 필요는 없습니다.

요청

헤더

헤더	필수	설명
`Authorization`	예	`Bearer <your API key>`
`Content-Type`	예	`application/json`
`Idempotency-Key`	권장	출력 가능한 ASCII 문자 1–255자로 된 임의의 문자열. 같은 키로 재시도하면 절대 두 번 차감되지 않습니다. 멱등성을 참고하세요.

본문

필드	타입	필수	설명
`video_url`	string	예	동영상의 공개 `http(s)` URL 또는 /uploads가 반환한 `video_url`.
`resolution`	string	예	`1080p`, `2k` 또는 `4k`.

동영상 요구 사항

형식: MP4, MOV, WebM.
길이: 최대 600초.
크기: 원격 video_url은 최대 500MB, /uploads를 통한 업로드는 최대 100MB.
video_url의 서버는 일반 GET 요청에 파일과 Content-Length 헤더로 응답해야 합니다. S3, R2, Google Cloud Storage의 서명된 링크는 사용할 수 있습니다. YouTube나 Google Drive 미리보기 같은 공유 페이지는 사용할 수 없습니다.
전체 길이 정보가 없는 조각화된(fragmented) MP4 파일은 거부됩니다. 먼저 일반 MP4로 다시 인코딩하세요.
WebM 파일은 헤더에 길이 정보가 있어야 합니다. 브라우저에서 녹화한 파일(MediaRecorder)에는 없는 경우가 많으니 먼저 다시 인코딩하세요.

예시

curl https://videoupscaler.co/api/v1/upscale \
  -H "Authorization: Bearer $VIDEOUPSCALER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{"video_url": "https://example.com/clip.mp4", "resolution": "2k"}'

const res = await fetch('https://videoupscaler.co/api/v1/upscale', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEOUPSCALER_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1234',
  },
  body: JSON.stringify({ video_url: 'https://example.com/clip.mp4', resolution: '2k' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const task = await res.json();

res = requests.post(
    "https://videoupscaler.co/api/v1/upscale",
    headers={
        "Authorization": f"Bearer {os.environ['VIDEOUPSCALER_API_KEY']}",
        "Idempotency-Key": "order-1234",
    },
    json={"video_url": "https://example.com/clip.mp4", "resolution": "2k"},
    timeout=300,
)
res.raise_for_status()
task = res.json()

응답

201 Created와 함께 작업을 반환합니다.

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

이후 작업이 completed가 될 때까지 작업을 폴링하세요.

이 요청은 응답하기 전에 동영상을 다운로드하므로, 원격 파일이 크면 시간이 걸릴 수 있습니다. 타임아웃은 최소 5분으로 설정하세요.

멱등성

모든 요청에 Idempotency-Key를 보내고, 타임아웃이나 네트워크 오류 후 재시도할 때 같은 키를 다시 사용하세요.

같은 키에 같은 video_url과 resolution을 보내면 원래 작업을 200 OK로 반환합니다. 크레딧은 다시 차감되지 않습니다.
같은 키에 다른 video_url 또는 resolution을 보내면 409 idempotency_conflict를 반환합니다.
헤더가 없으면 요청할 때마다 새 작업이 생성되고 크레딧이 차감됩니다.

요금

가격은 동영상 길이(초 단위, 올림)에 해상도별 요율을 곱한 값입니다. 크레딧 및 요금을 참고하세요. 12.4초 동영상을 2K로 처리하면 13 × 2 = 26 크레딧입니다.

작업이 실패하면 크레딧은 자동으로 환불되고 작업 상태는 failed가 됩니다.

오류

상태	코드	발생 조건
`400`	`invalid_request`	`video_url`, `resolution` 또는 `Idempotency-Key`가 없거나 잘못됨
`401`	`unauthorized`	API 키가 없거나 유효하지 않음
`403`	`paid_plan_required`	계정이 크레딧을 구매하거나 구독한 적이 없음
`402`	`insufficient_credits`	잔액이 동영상 처리 비용보다 부족함
`409`	`idempotency_conflict`	해당 `Idempotency-Key`가 다른 파라미터로 이미 사용됨
`413`	`file_too_large`	동영상이 500MB를 초과함
`422`	`video_fetch_failed`	`video_url`을 다운로드할 수 없음
`422`	`unsupported_video`	읽을 수 있는 MP4, MOV, WebM 파일이 아니거나 길이 정보가 없음
`422`	`video_too_long`	동영상이 600초를 초과함
`422`	`video_not_found`	업로드된 `video_url`에 파일이 없음(업로드가 완료되지 않음)
`504`	`upstream_timeout`	`video_url` 다운로드가 4분을 초과함

오류 형식은 오류를 참고하세요.

POST https://videoupscaler.co/api/v1/upscale

요청

헤더

헤더	필수	설명
`Authorization`	예	`Bearer <your API key>`
`Content-Type`	예	`application/json`
`Idempotency-Key`	권장	출력 가능한 ASCII 문자 1–255자로 된 임의의 문자열. 같은 키로 재시도하면 절대 두 번 차감되지 않습니다. 멱등성을 참고하세요.

본문

필드	타입	필수	설명
`video_url`	string	예	동영상의 공개 `http(s)` URL 또는 /uploads가 반환한 `video_url`.
`resolution`	string	예	`1080p`, `2k` 또는 `4k`.

동영상 요구 사항

형식: MP4, MOV, WebM.
길이: 최대 600초.
크기: 원격 video_url은 최대 500MB, /uploads를 통한 업로드는 최대 100MB.
video_url의 서버는 일반 GET 요청에 파일과 Content-Length 헤더로 응답해야 합니다. S3, R2, Google Cloud Storage의 서명된 링크는 사용할 수 있습니다. YouTube나 Google Drive 미리보기 같은 공유 페이지는 사용할 수 없습니다.
전체 길이 정보가 없는 조각화된(fragmented) MP4 파일은 거부됩니다. 먼저 일반 MP4로 다시 인코딩하세요.
WebM 파일은 헤더에 길이 정보가 있어야 합니다. 브라우저에서 녹화한 파일(MediaRecorder)에는 없는 경우가 많으니 먼저 다시 인코딩하세요.

예시

curl https://videoupscaler.co/api/v1/upscale \
  -H "Authorization: Bearer $VIDEOUPSCALER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{"video_url": "https://example.com/clip.mp4", "resolution": "2k"}'

const res = await fetch('https://videoupscaler.co/api/v1/upscale', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEOUPSCALER_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1234',
  },
  body: JSON.stringify({ video_url: 'https://example.com/clip.mp4', resolution: '2k' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const task = await res.json();

res = requests.post(
    "https://videoupscaler.co/api/v1/upscale",
    headers={
        "Authorization": f"Bearer {os.environ['VIDEOUPSCALER_API_KEY']}",
        "Idempotency-Key": "order-1234",
    },
    json={"video_url": "https://example.com/clip.mp4", "resolution": "2k"},
    timeout=300,
)
res.raise_for_status()
task = res.json()

응답

201 Created와 함께 작업을 반환합니다.

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

이후 작업이 completed가 될 때까지 작업을 폴링하세요.

이 요청은 응답하기 전에 동영상을 다운로드하므로, 원격 파일이 크면 시간이 걸릴 수 있습니다. 타임아웃은 최소 5분으로 설정하세요.

멱등성

모든 요청에 Idempotency-Key를 보내고, 타임아웃이나 네트워크 오류 후 재시도할 때 같은 키를 다시 사용하세요.

같은 키에 같은 video_url과 resolution을 보내면 원래 작업을 200 OK로 반환합니다. 크레딧은 다시 차감되지 않습니다.
같은 키에 다른 video_url 또는 resolution을 보내면 409 idempotency_conflict를 반환합니다.
헤더가 없으면 요청할 때마다 새 작업이 생성되고 크레딧이 차감됩니다.

요금

작업이 실패하면 크레딧은 자동으로 환불되고 작업 상태는 failed가 됩니다.

오류

상태	코드	발생 조건
`400`	`invalid_request`	`video_url`, `resolution` 또는 `Idempotency-Key`가 없거나 잘못됨
`401`	`unauthorized`	API 키가 없거나 유효하지 않음
`403`	`paid_plan_required`	계정이 크레딧을 구매하거나 구독한 적이 없음
`402`	`insufficient_credits`	잔액이 동영상 처리 비용보다 부족함
`409`	`idempotency_conflict`	해당 `Idempotency-Key`가 다른 파라미터로 이미 사용됨
`413`	`file_too_large`	동영상이 500MB를 초과함
`422`	`video_fetch_failed`	`video_url`을 다운로드할 수 없음
`422`	`unsupported_video`	읽을 수 있는 MP4, MOV, WebM 파일이 아니거나 길이 정보가 없음
`422`	`video_too_long`	동영상이 600초를 초과함
`422`	`video_not_found`	업로드된 `video_url`에 파일이 없음(업로드가 완료되지 않음)
`504`	`upstream_timeout`	`video_url` 다운로드가 4분을 초과함

오류 형식은 오류를 참고하세요.

업스케일 생성

요청

헤더

본문

동영상 요구 사항

예시

응답

멱등성

요금

오류

On this page

업스케일 생성

요청

헤더

본문

동영상 요구 사항

예시

응답

멱등성

요금

오류

On this page