개발자 API

동영상을 원하는 파일 크기로 정확하게 압축하세요

공개 동영상 URL을 보내거나 파일을 업로드하세요. VidSmaller가 비동기로 압축을 실행하고 진행 상황을 알려주며 다운로드 가능한 결과를 반환합니다.

OpenAPI 다운로드Postman 컬렉션 다운로드Postman에서 열기
업데이트
업데이트: 2026-10-17
한도 확인일
한도 확인일: 2026-09-14
VidSmaller 크레딧이 사용됩니다
VidSmaller 크레딧이 사용됩니다
이 페이지의 내용

3단계로 시작하기

키를 만들고 동영상을 제출한 뒤, 작업 상태를 폴링하거나 서명된 웹훅을 기다리세요.

  1. 1

    키 만들기

    대시보드에서 키 이름을 지정하세요. API 키와 웹훅 시크릿이 표시되면 바로 복사하세요. 두 값 모두 한 번만 표시됩니다.

  2. 2

    작업 생성

    공개 URL을 보내거나 파일을 업로드한 뒤 target_size_mb를 지정하고, 필요에 따라 코덱, 해상도, 포맷 설정을 선택하세요.

  3. 3

    결과 받기

    작업 상태를 폴링하거나 서명된 웹훅을 받으세요. 완료된 작업에는 유효 기간이 짧은 인증 다운로드 URL이 포함됩니다.

무료 읽기 전용 엔드포인트

플랫폼 한도 및 예측 요청은 API 키가 필요 없으며 IP당 시간당 600회 요청을 허용합니다.

동일한 압축 워크플로

인증된 작업은 웹 압축기와 동일한 크레딧, 파일 한도, 코덱 이용 권한, 버스트 한도를 사용합니다.

두 가지 입력 방식

공개 동영상 직접 링크(URL)를 사용하거나, 로컬 파일용 서명된 업로드 URL을 요청하세요.

안정적인 v1 규약

새 필드가 추가될 수는 있지만 기존 v1 필드의 의미는 변경되지 않습니다.

인증 및 크레딧

압축 작업과 업로드에만 인증이 필요합니다. 읽기 전용 플랫폼 및 예측 엔드포인트는 공개되어 있습니다.

Bearer API 키

API Keys 대시보드에서 키를 생성하세요. 전체 값은 다시 표시되지 않으므로 안전하게 보관하세요.

Authorization: Bearer $VIDSMALLER_API_KEY

공용 크레딧 잔액

API에는 별도 요금제가 없습니다. 작업 생성 시 크레딧이 예약되고 실제 인코더 사용 시간에 따라 정산되며, 처리에 실패하면 자동으로 환불됩니다.

/api/v1/platforms

VidSmaller가 추적하는 모든 업로드 한도를 안전한 압축 목표치, 출처 링크, 각 한도의 확인 날짜와 함께 반환합니다.

GET

8개 플랫폼을 반환합니다. 인증이나 매개변수가 필요하지 않습니다.

curl -s https://vidsmaller.com/api/v1/platforms

응답 필드

statedLimitMbnumber

해당 플랫폼이 기본 등급에 대해 공식적으로 안내하는 업로드 한도입니다.

safeTargetMbnumber

인코더 편차를 감안해 여유를 둔 약간 더 낮은 압축 목표치입니다.

tierNotestring | null

공식 한도가 계정 유형, 앱, API 접근 권한에 따라 달라질 때 제공되는 유의 사항입니다.

tiers[]array

문서화된 모든 무료, 유료, 봇, 클라이언트별 등급과 참고 사항입니다.

verifiedAtdate

담당자가 해당 플랫폼의 공식 문서를 마지막으로 확인한 날짜입니다.

sources[]array

한도를 확인하는 데 사용한 출처 페이지입니다.

/api/v1/estimate

파일이 대상 플랫폼에 맞는지 확인하고 압축 설정의 결과물을 예측합니다. GET 쿼리 필드와 POST JSON 본문은 동일한 이름을 사용합니다.

GET · POSTAPI 키 불필요
curl -s "https://vidsmaller.com/api/v1/estimate?sizeMb=150.7&durationSeconds=596&platform=discord"

요청 필드

sizeBytesinteger

원본 파일 크기(바이트)입니다. sizeMb를 제공하지 않으면 필수입니다.

sizeMbnumber

원본 크기(MiB)이며, 1MB는 1,048,576바이트입니다.

durationSecondsnumber

선택 항목인 재생 시간입니다. 이 값이 없으면 화질과 비트레이트를 예측할 수 없으므로 입력을 강력히 권장합니다.

width, heightinteger

선택 항목인 원본 해상도입니다. 해상도 변경을 예측할 때만 필요합니다.

platformstring

선택 항목으로, /api/v1/platforms에서 가져온 플랫폼 키입니다. 해당 플랫폼의 안전 목표치를 적용합니다.

targetMbnumber

선택 항목인 사용자 지정 파일 크기 상한입니다. 선택한 플랫폼 목표치보다 우선 적용됩니다.

settingsobject

선택 항목인 압축 설정: mode, preset, targetSizeMb, crf, resolution, maxResolution, bitrateKbps, codec, outputFormat.

응답 필드

verdictstring

fits_as_is, compress_recommended, no_target 중 하나입니다. 애플리케이션 로직에서 안전하게 사용할 수 있습니다.

estimateobject | null

요청한 설정에 대한 예상 결과물입니다. 입력값만으로 신뢰할 수 있는 예측이 불가능하면 null입니다.

recommendationobject | null

목표에 맞을 것으로 예상되는 설정이며, 예상 비디오 비트레이트와 화질 가이드를 포함합니다.

notes[]string[]

최종 사용자에게 보여주기 좋은 알기 쉬운 유의 사항입니다.

compressUrlstring

작업을 직접 마무리하려는 사용자를 위한 VidSmaller 웹 도구 링크입니다.

응답 예시

{
  "ok": true,
  "input": { "sizeBytes": 158020403, "sizeMb": 150.7, "durationSeconds": 596 },
  "target": {
    "platform": "discord",
    "safeTargetMb": 19,
    "statedLimitMb": 20,
    "verifiedAt": "2026-09-14"
  },
  "verdict": "compress_recommended",
  "fitsAsIs": false,
  "estimate": {
    "settings": { "mode": "preset", "preset": "balanced", "codec": "libx264" },
    "outputMb": 90.4,
    "savedPercent": 40,
    "fitsTarget": false,
    "jobSeconds": 123
  },
  "recommendation": {
    "settings": { "mode": "target_size", "targetSizeMb": 19 },
    "outputMb": 19,
    "quality": { "videoKbps": 134, "verdict": "rough" }
  }
}

/api/v1/video/jobs

target_size_mb를 목표로 하는 비동기 압축 작업을 생성합니다. 공개 소스 URL 또는 업로드한 파일의 토큰 중 하나를 사용하세요.

POSTBearer API 키 필요

옵션 A: 공개 동영상 URL

공개적으로 접근 가능한 동영상 파일 직접 링크에는 source_url을 사용하세요. VidSmaller는 크레딧을 예약하기 전에 실제 원본 크기를 확인합니다.

curl -s https://vidsmaller.com/api/v1/video/jobs \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.example.com/input.mp4",
    "target_size_mb": 25,
    "codec": "h264",
    "max_resolution": "1080p",
    "webhook_url": "https://example.com/webhooks/vidsmaller"
  }'

옵션 B: 로컬 파일 업로드

서명된 업로드 URL을 요청하고 해당 URL로 파일을 직접 PUT한 뒤, 반환된 upload_token으로 작업을 생성하세요.

# 1. Request a one-hour signed upload URL
curl -s https://vidsmaller.com/api/v1/video/uploads \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"input.mp4","file_size":52428800,"content_type":"video/mp4"}'

# 2. PUT the file to upload.url with the returned Content-Type header
# 3. Create the job with the returned upload_token
curl -s https://vidsmaller.com/api/v1/video/jobs \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_token":"UPLOAD_TOKEN","target_size_mb":25}'

요청 필드

source_urlHTTPS URL

공개 동영상 직접 링크입니다. upload_token과 둘 중 하나만 사용하며, 동시에 사용할 수 없습니다.

upload_tokenstring

서명된 업로드 URL을 요청한 뒤 반환되는 토큰입니다. source_url과 둘 중 하나를 사용하세요.

target_size_mbnumber

필수 항목으로, 출력 크기 상한(MiB)입니다.

codecstring

기본값은 h264이며, 계정의 유료 권한이 허용하는 경우 h265를 사용할 수 있습니다.

max_resolutionstring

선택 항목인 해상도 상한: 2160p, 1440p, 1080p, 720p, 576p, 480p, 360p.

output_formatstring

선택 항목인 출력 컨테이너: 기본값 mp4, 또는 mkv, webm, mov.

webhook_urlHTTPS URL

선택 항목인 종료 이벤트 콜백입니다. 사설망 주소와 리디렉션은 거부됩니다.

상태 확인 및 다운로드

job.status가 completed 또는 failed가 될 때까지 폴링하세요. 완료된 작업은 인증이 필요한 단기 유효 download_url을 반환합니다. 상태 조회와 다운로드 요청에는 동일한 Bearer 키를 사용하세요.

curl -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  https://vidsmaller.com/api/v1/video/jobs/JOB_ID

서명된 웹훅

작업이 최종 상태에 도달하면 폴링 대신 콜백을 받을 수 있습니다.

이벤트는 video.job.completed, video.job.failed, video.job.expired입니다.

검증 대상: x-vidsmaller-signature — 다음 값에 대해 HMAC-SHA256을 계산하세요: timestamp + "." + rawBody.

API 키를 생성할 때 표시된 웹훅 서명 시크릿을 사용하세요. 서명 헤더는 v1=로 시작합니다.

오류

오류는 JSON 응답으로 반환됩니다. 상태 코드를 통해 요청을 수정할지, 다시 인증할지, 크레딧을 구매할지, 나중에 재시도할지 판단할 수 있습니다.

400

요청 필드가 잘못되었거나 누락되었습니다.

오류 메시지를 확인하고 페이로드를 수정하세요.

401

API 키가 없거나 유효하지 않거나 삭제되었습니다.

유효한 Bearer 키를 보내거나 새로 생성하세요.

402

작업에 필요한 크레딧이 부족합니다.

크레딧을 충전한 뒤 작업을 다시 생성하세요.

404

해당 키로 조회되는 작업 또는 다운로드가 없습니다.

ID를 확인하고 작업을 생성한 키를 사용하세요.

409

업로드 또는 작업이 필요한 상태가 아닙니다.

다시 시도하기 전에 현재 상태를 확인하세요.

429

요청 수 또는 동시 실행 한도에 도달했습니다.

잠시 기다린 후 백오프를 적용해 재시도하세요.

500

VidSmaller가 요청을 완료하지 못했습니다.

나중에 다시 시도하세요. 문제가 계속되면 지원팀에 문의하세요.

한도 및 적정 사용

API는 웹 압축기와 동일한 제품 한도를 따릅니다.

  • 공개 읽기 전용 엔드포인트는 IP당 시간당 600회 요청을 허용합니다.
  • 압축 작업은 계정의 크레딧, 파일 크기 한도, 코덱 이용 권한, 버스트 한도를 사용합니다.
  • API v1에는 응답 필드가 추가될 수 있지만 기존 필드의 의미는 변경되지 않습니다.
  • 상업적 이용이 가능합니다. VidSmaller 링크를 남겨주시면 감사하지만 필수는 아닙니다.

플랫폼 한도가 잘못되었거나 API 요청이 예상과 다르게 동작하면 다음 주소로 이메일을 보내주세요: support@vidsmaller.com

관련 자료

동영상 압축 계산기Discord 업로드 한도서비스 약관
홈으로 돌아가기