API

认证

Base URL:

https://api.bgless.video/v1

Unscreen 迁移兼容接口：

https://api.bgless.video/v1.0/videos

在 /settings/apikeys 创建 API key。

Authorization: Bearer sk_...

也支持 X-Api-Key。

API key 可选设置月度 credits 配额。创建任务时如果会超出该 key 的配额，接口会在提交 provider 前返回 429 rate_limited。

上传

先申请 presigned 上传 URL：

curl -X POST https://api.bgless.video/v1/uploads \
  -H "Authorization: Bearer $BGLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "input.mp4",
    "contentType": "video/mp4",
    "sizeBytes": 123456
  }'

响应：

{
  "data": {
    "uploadUrl": "https://storage.example.com/presigned-put-url",
    "fileUrl": "https://cdn.example.com/uploads/source/file.mp4",
    "method": "PUT",
    "headers": {
      "Content-Type": "video/mp4"
    },
    "fileUrlExpiresAt": "2026-05-08T12:00:00.000Z",
    "sizeBytes": 123456,
    "uploaded": false,
    "directUpload": true
  }
}

然后用返回的 headers 向 data.uploadUrl 发起 PUT 上传，创建任务时使用 data.fileUrl。同源 R2 文件 URL 会带签名，并在 24 小时后过期。

如果文件已经托管在公网，可以直接发送 { "url": "https://example.com/input.mp4" }，并使用返回的 fileUrl。

预估任务

提交 provider 任务前，先预估 credits、ETA 和当前余额。这个接口不会创建任务，也不会消耗 KIE credits。

curl -X POST https://api.bgless.video/v1/jobs/estimate \
  -H "Authorization: Bearer $BGLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "mode": "text",
      "prompt": "a floating product bottle rotating slowly",
      "durationSec": 3,
      "resolution": "720p"
    },
    "options": {
      "outputs": ["webm-vp9-alpha"],
      "preset": "web-app"
    }
  }'

响应：

{
  "data": {
    "provider": "kie",
    "model": "kie.kling-3-video",
    "credits": 48,
    "etaSec": 120,
    "remainingCredits": 100,
    "quota": null,
    "canAfford": true
  }
}

如果浏览器里选择了本地文件但还没有上传，Web app 也可以先根据模式、时长、分辨率、输出格式和模型做预估。

模型列表

查询当前可公开使用的 RGBA 模型：

curl https://api.bgless.video/v1/models

响应里包含模型 id、provider、展示名、支持的模式、能力和输出类型。创建或预估任务时，可把返回的模型 id 作为 model 传入。

创建任务

curl -X POST https://api.bgless.video/v1/jobs \
  -H "Authorization: Bearer $BGLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "mode": "video",
      "videoUrl": "https://cdn.example.com/input.mp4",
      "resolution": "1080p",
      "refineEdges": true
    },
    "options": {
      "outputs": ["webm-vp9-alpha", "mov-prores4444"],
      "preset": "web-app",
      "callbackUrl": "https://example.com/webhooks/bgless",
      "callbackSecret": "replace-with-your-secret"
    }
  }'

返回 202 Accepted，包含任务和 pollUrl。

/api/v1/alpha-videos 是 /api/v1/jobs 的兼容别名。

支持的输出值包括 webm-vp9-alpha、mov-prores4444、animated-webp、gif、apng、png-sequence 和 matte-grayscale-mp4。

Unscreen 兼容接口

从旧 Unscreen API 迁移时，可以继续使用 X-Api-Key，并向 POST /v1.0/videos 发送 video_url 或 video_file。

curl -X POST https://api.bgless.video/v1.0/videos \
  -H "X-Api-Key: $BGLESS_API_KEY" \
  -F "video_url=https://cdn.example.com/input.mp4" \
  -F "format=pro_bundle" \
  -F "webhook_url=https://example.com/webhooks/unscreen"

兼容层会把 pro_bundle 映射为 bgless 的 WebM alpha 加 alpha matte MP4，返回 Unscreen 风格的 data.type = "video" 响应，并支持 GET /v1.0/videos/:id 和 DELETE /v1.0/videos/:id。

短任务可以要求服务端有限等待：

curl -X POST "https://api.bgless.video/v1/jobs?wait=true&timeout=30" \
  -H "Authorization: Bearer $BGLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

如果任务在 timeout 内进入终态，API 返回 200。如果任务仍在排队、处理中或转码中，API 仍返回 202 和 pollUrl。

如果已有视频本身带 alpha，只需要做格式转换，请把 input.alphaStrategy 设为 preserve-source-alpha。任务会直接路由到本地转码器（local.ffmpeg-encoder），不会提交 KIE 生成任务。

查询任务

curl https://api.bgless.video/v1/jobs/job_id \
  -H "Authorization: Bearer $BGLESS_API_KEY"

转码成功的任务会包含 outputAssets、棋盘格/深色/浅色 previewAssets，以及 qaReport。QA JSON 附件也会以 kind: "qa" 出现在 previewAssets 中。

状态包括 queued、submitted、processing、transcoding、success、failed、canceled。

下载

curl -L "https://api.bgless.video/v1/jobs/job_id/download?format=webm-vp9-alpha" \
  -H "Authorization: Bearer $BGLESS_API_KEY"

删除

curl -X DELETE https://api.bgless.video/v1/jobs/job_id \
  -H "Authorization: Bearer $BGLESS_API_KEY"

删除运行中的任务时，系统会先取消任务，再从任务历史中隐藏。如果资产存储在 R2，删除任务时也会尽力删除对应的源文件、输出、预览和 QA 对象。

用户 Webhook

设置 options.callbackUrl 后，终态任务会回调用户 webhook。设置 options.callbackSecret 后会附带：

X-Bgless-Signature: t=unix_timestamp,v1=hmac_sha256(secret, t + "." + body)

事件包括 job.completed、job.failed、job.canceled。

Provider Webhook

KIE 回调地址：

https://bgless.video/api/v1/webhooks/kie

生产环境需要配置 KIE_WEBHOOK_HMAC_KEY。

API

On this page