REST API
파일 업로드 및 공유
이 튜토리얼에서는 데모.mp4라는 로컬 파일 하나를 가져와서 작업 공유 URL로 변환합니다. 단계를 순서대로 완료하세요. 각 응답은 다음 요청에 사용되는 값을 제공합니다.
API 키 생성 및 저장
개발자 설정을 열고 uploads:write, files:read, shares:write 및 shares:read를 선택한 다음 키를 만듭니다. 지금 복사하세요. 전체 비밀은 한 번만 표시됩니다.
사용 가능한 범위: uploads:write, files:read, files:write, shares:write, shares:read, domains:read 및 domains:write.
터미널 준비
모든 명령이나 셸 기록에 표시되지 않도록 환경 변수에 키를 넣으세요. Enter 키를 누르기 전에 자리 표시자를 바꾸세요.
read -s VIDEO2URL_API_KEY
echo "key loaded"업로드 작업 만들기
Video2URL에 정확한 파일 이름, MIME 유형 및 바이트 크기를 알려주십시오. 그러면 임시 R2 업로드 URL이 반환됩니다. 아직 영상은 업로드되지 않습니다.
POST /api/v1/uploads
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}'export UPLOAD_ID="paste data.uploadId here"
export UPLOAD_URL="paste data.upload.url here"비디오 바이트 보내기
데모.mp4를 임시 URL에 직접 업로드하세요. 이 PUT 요청에 Video2URL API 키를 추가하지 마세요. 생성-업로드 응답에서 반환된 Content-Type을 사용하세요. 반환된 콘텐츠 유형을 사용하여 미리 서명된 URL에 원시 파일을 업로드합니다.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
-H "If-None-Match: *" \
--data-binary @demo.mp4업로드 완료 및 확인
PUT이 성공한 후 Video2URL에 저장된 개체를 확인하고 파일 레코드를 생성하도록 지시합니다. PUT이 완료되기 전에 이 단계를 호출하지 마세요.
POST /api/v1/uploads/{uploadId}/complete · GET /api/v1/uploads/{uploadId}
curl -sS -X POST "https://video2url.com/api/v1/uploads/$UPLOAD_ID/complete" \
-H "Authorization: Bearer $VIDEO2URL_API_KEY"export FILE_ID="paste data.file.fileId here"Video2URL SDK · npm
npm install video2urlGET / 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}JavaScript & Python
필요한 가장 좁은 키를 만듭니다. 이전 키를 취소하기 전에 대체 키를 생성 및 배포하여 순환하세요. 유료 액세스가 종료되면 키는 계속 저장되지만 통화는 일시 중지됩니다. 적격 플랜을 갱신하면 액세스가 복원됩니다.
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 });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 내보내기를 보여줍니다.
- POST /api/v1/uploads 를 통해 업로드 세션 요청
- 후속 PUT을 위해 반환된 uploadId 및 upload.url 저장
Video2URL · · English
스크린샷은 영어 인터페이스를 반영하며, 주석은 현재 언어를 따릅니다.
전체 예제 다운로드 및 실행
node upload-share.mjs api ./report.pdf application/pdf이용 방법
- 업로드 및 공유 scope 4개가 모두 활성화된 개발자 API 키를 발급받습니다.
- POST /api/v1/uploads를 전송하고 upload.headers를 사용하여 raw 바이트를 PUT한 다음 POST /api/v1/uploads/{uploadId}/complete를 전송합니다.
- 파일 status가 ready인지 확인하고 확인된 fileId와 함께 POST /api/v1/shares를 전송합니다.
사용자 지정 링크 슬러그
사용자 지정 슬러그는 Pro 또는 Business 플랜에서만 사용할 수 있습니다.
3~48자(영문 소문자 a-z, 0-9, 하이픈 -), 시작과 끝은 영문자 또는 숫자여야 합니다. 비워두면 자동 생성됩니다.
POST /api/v1/shares
{ "fileId": "<FILE_ID>", "visibility": "unlisted", "customSlug": "product-demo" }
409 CUSTOM_SLUG_CONFLICT이미 사용 중인 슬러그입니다. 다른 슬러그를 입력한 후 다시 시도해 주세요.
