REST API

上傳和共享文件

本教學採用一個名為 demo.mp4 的本機文件，並將其轉換為工作共享 URL。依序完成步驟；每個回應提供一個供下一個請求使用的值。

建立並儲存 API 密鑰

開啟開發者設置，選擇 uploads:write、files:read、shares:write 和 shares:read，然後建立金鑰。立即複製——完整的秘密僅顯示一次。

可用範圍：uploads:write、files:read、shares:write 和 shares:read。

預期結果：您有一個以 Video2URL 密鑰前綴開頭的秘密。保密。

準備您的終端

將密鑰放入環境變數中，這樣它就不會出現在每個命令或 shell 歷史記錄中。按 Enter 鍵之前取代佔位符。

Terminal

read -s VIDEO2URL_API_KEY
echo "key loaded"

預期結果：該命令列印載入的密鑰，而不是秘密本身。

建立上傳作業

告訴 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"

傳送視訊位元組

直接上傳demo.mp4到臨時URL。請勿將 Video2URL API 金鑰加入此 PUT 請求中。使用建立上傳回應傳回的內容類型。使用傳回的內容類型將原始檔案上傳到預先簽署的 URL。

curl · PUT

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @demo.mp4

預期結果：上傳伺服器返回HTTP 200。回應正文為空是正常的。

完成並驗證上傳

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"

建立最終共享 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

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();

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:
    requests.put(created.json()["data"]["upload"]["url"], data=video).raise_for_status()