REST API

上传和共享文件

这份教程会把本地的 demo.mp4 转换成一个可以打开的分享 URL。请按顺序完成；每一步响应里的值都会在下一步使用。

创建并保存 API 密钥

打开开发者设置，勾选 uploads:write、files:read、shares:write 和 shares:read，然后创建密钥。请立即复制——完整密钥只显示一次。

可用权限范围：uploads:write、files:read、shares:write 和 shares:read。

预期结果：你已经得到一段以 Video2URL 密钥前缀开头的秘密字符串。不要分享给任何人。

准备终端

把密钥放入环境变量，避免每条命令都出现密钥，也避免它进入终端历史记录。按回车前先替换占位符。

Terminal

read -s VIDEO2URL_API_KEY
echo "key loaded"

预期结果：命令只输出“key loaded”，不会显示真正的密钥。

创建上传任务

告诉 Video2URL 准确的文件名、MIME 类型和字节数。响应会返回一个临时 R2 上传地址；这一步还没有上传视频。

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}'

预期结果：JSON 响应包含 data.uploadId 和 data.upload.url。保存这两个值，下一步会用到。

Save response values

export UPLOAD_ID="paste data.uploadId here"
export UPLOAD_URL="paste data.upload.url here"

发送视频文件内容

把 demo.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。响应正文为空是正常情况。

完成并验证上传

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