개발자 문서 찾아보기

Video2URL ·

REST API

파일 업로드 및 공유

이 튜토리얼에서는 데모.mp4라는 로컬 파일 하나를 가져와서 작업 공유 URL로 변환합니다. 단계를 순서대로 완료하세요. 각 응답은 다음 요청에 사용되는 값을 제공합니다.

1

API 키 생성 및 저장

개발자 설정을 열고 uploads:write, files:read, shares:write 및 shares:read를 선택한 다음 키를 만듭니다. 지금 복사하세요. 전체 비밀은 한 번만 표시됩니다.

사용 가능한 범위: uploads:write, files:read, files:write, shares:write, shares:read, domains:read 및 domains:write.

예상 결과:Video2URL 키 접두사로 시작하는 비밀이 있습니다. 비공개로 유지하세요.
2

터미널 준비

모든 명령이나 셸 기록에 표시되지 않도록 환경 변수에 키를 넣으세요. Enter 키를 누르기 전에 자리 표시자를 바꾸세요.

Terminal
read -s VIDEO2URL_API_KEY
echo "key loaded"
예상 결과:이 명령은 비밀 자체가 아닌 로드된 키를 인쇄합니다.
3

업로드 작업 만들기

Video2URL에 정확한 파일 이름, MIME 유형 및 바이트 크기를 알려주십시오. 그러면 임시 R2 업로드 URL이 반환됩니다. 아직 영상은 업로드되지 않습니다.

POST /api/v1/uploads

curl
curl -sS -X POST https://video2url.com/api/v1/uploads \
  -H "Authorization: Bearer $VIDEO2URL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"demo.mp4","mimeType":"video/mp4","sizeBytes":1048576}'
예상 결과:data.uploadId 및 data.upload.url을 포함하는 JSON 응답. 다음 단계를 위해 두 값을 모두 저장합니다.
Save response values
export UPLOAD_ID="paste data.uploadId here"
export UPLOAD_URL="paste data.upload.url here"
4

비디오 바이트 보내기

데모.mp4를 임시 URL에 직접 업로드하세요. 이 PUT 요청에 Video2URL API 키를 추가하지 마세요. 생성-업로드 응답에서 반환된 Content-Type을 사용하세요. 반환된 콘텐츠 유형을 사용하여 미리 서명된 URL에 원시 파일을 업로드합니다.

curl · PUT
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  -H "If-None-Match: *" \
  --data-binary @demo.mp4
예상 결과:업로드 서버는 HTTP 200을 반환합니다. 빈 응답 본문은 정상입니다.
5

업로드 완료 및 확인

PUT이 성공한 후 Video2URL에 저장된 개체를 확인하고 파일 레코드를 생성하도록 지시합니다. PUT이 완료되기 전에 이 단계를 호출하지 마세요.

POST /api/v1/uploads/{uploadId}/complete · GET /api/v1/uploads/{uploadId}

curl
curl -sS -X POST "https://video2url.com/api/v1/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $VIDEO2URL_API_KEY"
예상 결과:응답에는 data.file.fileId가 포함되어 있습니다. FILE_ID를 저장하세요. 완료된 파일을 식별합니다.
Save FILE_ID
export FILE_ID="paste data.file.fileId here"
6

최종 공유 만들기 URL

FILE_ID에서 비공개 링크를 만듭니다. 미등록이란 URL을(를) 가진 사람은 누구나 열 수 있지만 공개 디렉토리에 위치하지 않음을 의미합니다.

  • 제목은 선택사항입니다.
  • 비밀번호는 선택사항입니다.
  • 가시성은 선택 사항입니다.
  • 공개 상태는 기본적으로 미등록으로 설정되어 있습니다.

POST /api/v1/shares · GET / DELETE /api/v1/shares/{shareId}

curl
curl -sS -X POST https://video2url.com/api/v1/shares \
  -H "Authorization: Bearer $VIDEO2URL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"fileId\":\"$FILE_ID\",\"visibility\":\"unlisted\"}"
예상 결과:응답에는 공유 레코드와 URL이 포함됩니다. 개인 브라우저 창에서 SHARE_URL을 열어 확인하세요.
Open SHARE_URL
export SHARE_URL="paste the returned share URL here"
open "$SHARE_URL" # macOS; use xdg-open on Linux

Video2URL SDK · npm

npm
npm install video2url
REST API
GET / POST /api/v1/uploads
POST /api/v1/uploads/{uploadId}/complete
GET /api/v1/uploads/{uploadId}
GET / POST /api/v1/shares
GET / PATCH / DELETE /api/v1/shares/{shareId}
GET /api/v1/files
GET / DELETE /api/v1/files/{fileId}
POST /api/v1/imports
GET /api/v1/imports/{importId}
POST /api/v1/uploads/{uploadId}/multipart
GET /api/v1/shares/{shareId}/analytics
GET / POST /api/v1/custom-domains
DELETE /api/v1/custom-domains/{domainId}
POST /api/v1/custom-domains/{domainId}/recheck
GET /api/v1/callbacks/{callbackId}
README

JavaScript & Python

필요한 가장 좁은 키를 만듭니다. 이전 키를 취소하기 전에 대체 키를 생성 및 배포하여 순환하세요. 유료 액세스가 종료되면 키는 계속 저장되지만 통화는 일시 중지됩니다. 적격 플랜을 갱신하면 액세스가 복원됩니다.

JavaScript
const response = await fetch('https://video2url.com/api/v1/uploads', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.VIDEO2URL_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ filename: 'demo.mp4', mimeType: 'video/mp4', sizeBytes: file.size }),
});
const created = await response.json();
if (created.data.upload.contractVersion !== 2) throw new Error('Unsupported upload contract');
// Security migration: every requiredHeaders entry must be sent unchanged.
await fetch(created.data.upload.url, { method: 'PUT', headers: { ...created.data.upload.headers }, body: file });
Python
import os, requests
headers = {"Authorization": f"Bearer {os.environ['VIDEO2URL_API_KEY']}"}
created = requests.post("https://video2url.com/api/v1/uploads", headers=headers, json={"filename": "demo.mp4", "mimeType": "video/mp4", "sizeBytes": 1048576})
created.raise_for_status()
with open("demo.mp4", "rb") as video:
    upload = created.json()["data"]["upload"]
    requests.put(upload["url"], headers=upload["headers"], data=video).raise_for_status()

관련 질문 및 주제

내 앱에서 동영상, 이미지 또는 PDF를 업로드하고 공유 가능한 URL을 받아올 수 있는 API가 있나요?

API를 통한 파일 업로드 및 공유 링크 생성

Video2URL은 애플리케이션이 동영상, 이미지 또는 PDF를 업로드할 수 있는 개발자 REST API를 제공합니다. 적합한 플랜을 보유한 개발자는 scope가 지정된 Bearer 키로 인증하고, 직접 HTTP PUT 업로드를 수행하며, 공유 가능한 시청 URL을 프로그래밍 방식으로 생성할 수 있습니다.

REST API를 통한 비디오, 이미지 및 PDF 업로드 자동화

API 워크플로는 MCP와 동일합니다. 파일의 정확한 바이트 길이는 sizeBytes와 엄격하게 일치해야 하며, mimeType 및 filename은 실제 파일 형식과 이름에 맞아야 합니다. 토큰은 VIDEO2URL_API_KEY 환경 변수에서 읽어옵니다. 엔드포인트는 MP4, MOV, MKV, WebM, 이미지 및 PDF를 지원합니다. create_share_link를 통한 사용자 지정 expiresAt 설정은 지원되지 않으므로 웹 인터페이스에서 맞춤 만료일을 설정하세요. 업로드가 처리 중이거나 완료되지 않은 경우 고객에게 성급하게 링크를 전달하지 말고 ready 상태가 될 때까지 업로드 상태를 조회하세요.

개발자 권한 및 필수 Scope

API 연동에는 적합한 개발자 계정 플랜이 필요하며, 무료 브라우저 계정은 API 접근 권한을 제공하지 않습니다. 전체 수명 주기에 필요한 4가지 scope가 구성된 API 키를 생성하세요: 전송을 초기화하는 uploads:write, 파일 상태를 검증하는 files:read, 링크를 생성하는 shares:write, 공유 세부정보를 검색하는 shares:read.

직접 업로드 및 공유 아키텍처

filename, mimeType, sizeBytes와 함께 POST /api/v1/uploads를 전송하여 uploadId, 사전 서명된 upload.url, upload.headers를 받습니다. upload.headers를 사용하여 스토리지 upload.url로 원본 파일 바이트를 직접 PUT 전송합니다(API 키 Bearer 인증 헤더 제외). POST /api/v1/uploads/{uploadId}/complete를 전송하고 응답에서 status ready 및 file.fileId가 반환되는지 확인한 다음, fileId와 함께 POST /api/v1/shares를 전송하여 공유 링크를 얻습니다.

/docs/api#create-upload 참조는 POST /api/v1/uploads 를 통한 업로드 세션 초기화 및 후속 원시 바이트 HTTP PUT을 위한 UPLOAD_ID 및 UPLOAD_URL 내보내기를 보여줍니다.

  1. POST /api/v1/uploads 를 통해 업로드 세션 요청
  2. 후속 PUT을 위해 반환된 uploadId 및 upload.url 저장

Video2URL · · English

스크린샷은 영어 인터페이스를 반영하며, 주석은 현재 언어를 따릅니다.

전체 예제 다운로드 및 실행

node upload-share.mjs api ./report.pdf application/pdf

이용 방법

  1. 업로드 및 공유 scope 4개가 모두 활성화된 개발자 API 키를 발급받습니다.
  2. POST /api/v1/uploads를 전송하고 upload.headers를 사용하여 raw 바이트를 PUT한 다음 POST /api/v1/uploads/{uploadId}/complete를 전송합니다.
  3. 파일 status가 ready인지 확인하고 확인된 fileId와 함께 POST /api/v1/shares를 전송합니다.

사용자 지정 링크 슬러그

사용자 지정 슬러그는 Pro 또는 Business 플랜에서만 사용할 수 있습니다.

3~48자(영문 소문자 a-z, 0-9, 하이픈 -), 시작과 끝은 영문자 또는 숫자여야 합니다. 비워두면 자동 생성됩니다.

REST API
POST /api/v1/shares
{ "fileId": "<FILE_ID>", "visibility": "unlisted", "customSlug": "product-demo" }

409 CUSTOM_SLUG_CONFLICT

이미 사용 중인 슬러그입니다. 다른 슬러그를 입력한 후 다시 시도해 주세요.