开发者 API

将视频压缩到指定大小

提交公开视频 URL 或上传本地文件。VidSmaller 会异步执行压缩、返回任务进度，并提供可下载的结果。

下载 OpenAPI下载 Postman 集合
更新时间
更新时间: 2026-10-10
限制数据核验于
限制数据核验于: 2026-09-14
使用 VidSmaller 账户积分
使用 VidSmaller 账户积分
本页目录

3 步开始使用

创建密钥、提交视频，然后轮询任务状态或等待签名 Webhook。

  1. 1

    创建密钥

    在控制台为密钥命名。API Key 和 Webhook Secret 只显示一次，请立即复制并妥善保存。

  2. 2

    创建任务

    提交公开视频 URL 或上传文件，设置 target_size_mb，并按需选择编码、最高分辨率和输出格式。

  3. 3

    获取结果

    轮询任务状态或接收签名 Webhook。任务完成后会返回需要鉴权的短期下载地址。

免费只读接口

平台限制与体积预估接口无需 API Key，每个 IP 每小时最多请求 600 次。

统一压缩流程

API 任务与网页压缩共用积分、文件限制、编码权限和并发限制。

两种输入方式

可使用公开视频直链，也可为本地文件申请签名上传地址。

稳定的 v1 契约

响应可以新增字段，但现有 v1 字段的含义不会改变。

鉴权与积分

只有文件上传和压缩任务需要鉴权；平台限制和体积预估接口可以直接调用。

Bearer API Key

在 API 密钥页面创建密钥。完整密钥不会再次显示，请安全保存。

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

已记录的免费、付费、Bot 或特定客户端档位及说明。

verifiedAtdate

人工对照平台官方文档进行最近一次核验的日期。

sources[]array

用于核验限制的官方来源页面。

/api/v1/estimate

判断文件是否符合目标平台限制，并预估指定压缩设置的输出结果。GET 查询参数与 POST JSON 使用相同字段名。

GET · POST无需 API Key
curl -s "https://vidsmaller.com/api/v1/estimate?sizeMb=150.7&durationSeconds=596&platform=discord"

请求字段

sizeBytesinteger

源文件字节数；未提供 sizeMb 时必填。

sizeMbnumber

源文件大小，单位 MiB；1 MB = 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，也可以是已上传文件的 token。

POST需要 Bearer API Key

方式 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：上传本地文件

先申请签名上传地址，将文件直接 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

申请签名上传地址后返回的 token。与 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；查询状态和下载时使用同一 API Key。

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

签名 Webhook

任务结束后接收回调，无需持续轮询。

事件包括 video.job.completed、video.job.failed 和 video.job.expired。

验证 x-vidsmaller-signature ：使用 HMAC-SHA256 计算 timestamp + "." + rawBody.

签名密钥会在创建 API Key 时显示。签名请求头以 v1= 开头。

错误处理

错误响应使用 JSON。HTTP 状态码会告诉你应该修正请求、重新鉴权、购买积分还是稍后重试。

400

请求字段缺失或格式无效。

根据错误信息修正请求体。

401

API Key 缺失、无效或已删除。

发送有效的 Bearer Key，或创建新密钥。

402

账户积分不足。

购买积分后重新创建任务。

404

当前 Key 无权访问该任务或下载。

检查 ID，并使用创建任务时的 Key。

409

上传或任务状态不符合当前操作要求。

查询最新状态后再决定是否重试。

429

达到请求频率或并发限制。

等待后采用退避策略重试。

500

VidSmaller 暂时无法完成请求。

稍后重试；持续发生时联系支持。

限制与合理使用

API 与网页压缩工具遵循相同的产品限制。

  • 公开只读接口每个 IP 每小时最多请求 600 次。
  • 压缩任务使用账户积分，并遵循账户的文件大小、编码权限和并发限制。
  • API v1 可以新增响应字段，但现有字段的含义不会改变。
  • 允许商业用途。欢迎链接到 VidSmaller，但不是强制要求。

如果平台限制有误，或 API 行为不符合预期，请发送邮件至 support@vidsmaller.com

相关资源

视频压缩计算器Discord 上传限制服务条款
返回首页