API

認証

ベース URL:

https://api.bgless.video/v1

非スクリーン互換の移行エンドポイントは次の場所から入手できます。

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

/settings/apikeys の API キーを使用します。

Authorization: Bearer sk_...

X-Api-Key も受け入れられます。

API キーには、オプションでプロジェクトラベルと月次クレジットクォータを含めることができます。キーがそのクォータを超えると、ジョブ作成はプロバイダーの作業を送信する前に「429 rate_limited」を返します。

クレジットはジョブの作成時に予約されます。失敗またはキャンセルされた RGBA ジョブは予約残高を復元し、監査履歴の「返金」クレジット台帳エントリを書き込みます。

アップロード

署名付きアップロードをリクエストします 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
  }
}

次に、返されたヘッダーを使用して、PUT でファイルを data.uploadUrl にアップロードします。ジョブを作成するときは data.fileUrl を使用します。同一オリジンの R2 ファイル URL は署名され、24 時間後に期限切れになります。

すでにホストされているファイルの場合は、{ "url": "https://example.com/input.mp4" } を送信し、返された fileUrl を使用します。

仕事の見積もり

プロバイダーの作業を送信する前に、クレジット、ETA、および現在の残高を見積もります。このエンドポイントはジョブを作成せず、KIE クレジットを消費しません。

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 アプリは直接アップロードする前に、モード、期間、解像度、出力、モデルから推定できます。

モデル

利用可能なパブリック RGBA モデルをリストします。

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

応答は「data.providers」および「data.models」として形成されます。各モデルには、その ID、プロバイダー、表示名、サポートされているモード、機能、および出力の種類が含まれます。ジョブを作成または見積もるときに、返されたモデル ID を「model」として使用します。ビデオアップロードワークフローは、ローカルトランスコーダを「local.ffmpeg-encoder」として公開します。

ノードSDK

型指定された Node.js SDK ソースは sdk/node に存在し、次のように公開されます。 @bgless/ノード。

pnpm sdk:node:typecheck
pnpm sdk:node:build

import { createBglessClient } from '@bgless/node';

const bgless = createBglessClient({
  apiKey: process.env.BGLESS_API_KEY!,
});

const job = await bgless.createJob({
  input: {
    mode: 'video',
    videoUrl: 'https://cdn.example.com/input.mp4',
    resolution: '1080p',
  },
  options: {
    outputs: ['webm-vp9-alpha'],
    callbackUrl: 'https://example.com/webhooks/bgless',
  },
});

console.log(job.data.id, job.pollUrl);

Python の例

Python SDK は M0 以降に予定されています。それまでは、「リクエスト」を直接使用してください。 REST API。

import os
import requests

response = requests.post(
    "https://api.bgless.video/v1/jobs",
    headers={
        "Authorization": f"Bearer {os.environ['BGLESS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "input": {
            "mode": "video",
            "videoUrl": "https://cdn.example.com/input.mp4",
            "resolution": "1080p",
        },
        "options": {
            "outputs": ["webm-vp9-alpha", "mov-prores4444"],
            "callbackUrl": "https://example.com/webhooks/bgless",
        },
    },
    timeout=30,
)

response.raise_for_status()
job = response.json()["data"]
print(job["id"], job["status"])

ジョブの作成

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

応答は、キューに入れられたジョブと pollUrl を含む 202 Accepted です。

/api/v1/alpha-videos は、alpha-video リソース名を好むクライアントのための /api/v1/jobs のエイリアスです。

サポートされている出力値は、webm-vp9-alpha、mov-prores4444、animated-webp、gif、apng、png-sequence、および matte-grayscale-mp4 です。

アンスクリーンの互換性

古い Unscreen API シェイプから移行する場合は、「X-Api-Key」と「video_url」または「video_file」を指定した「POST /v1.0/videos」を使用します。

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 マット MP4 にマップし、アンスクリーンスタイルの 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 '{ ... }'

ジョブがタイムアウト内に終了ステータスに達すると、API は「200」を返します。ジョブがまだキューに入れられている、処理中、またはトランスコーディング中の場合は、pollUrl とともに 202 を返します。

アップロードされたビデオワークフローの場合、auto、preserve-source-alpha、chroma-key、および ai-matting はデフォルトでローカルトランスコーダー (local.ffmpeg-encoder) にルーティングされ、KIE 生成タスクは送信されません。明示的な「ai-matting」の推定と作成は、トランスコーダが設定されたマッティングプロバイダーを報告するまで、ジョブの作成前にブロックされます。

クエリジョブ

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

成功したトランスコードされたジョブには、outputAssets、チェッカーボード/ダーク/ライトプレビュー用の previewAssets、および qaReport が含まれます。 QA JSON アーティファクトも、kind: "qa" で previewAssets にリストされます。

ステータス:

「キューに入れられました」
「提出済み」
「処理中」
「トランスコーディング」
「成功」
「失敗しました」
「キャンセルされました」

ダウンロード

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 です。

KIE からのプロバイダー Webhook は以下をターゲットにする必要があります:

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

本番環境で「KIE_WEBHOOK_HMAC_KEY」を設定します。

API

On this page