업스케일 생성

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

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

요청

헤더

본문

동영상 요구 사항

• 형식: MP4, MOV, WebM.
• 길이: 1080p는 최대 1200초, 2k·4k는 최대 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가 됩니다.

오류

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