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

아직 업로드되지 않은 브라우저 선택 파일의 경우 웹 앱은 직접 업로드하기 전에 모드, 기간, 해상도, 출력 및 모델을 추정할 수 있습니다.

모델

사용 가능한 공개 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 SDK는 M0 이후에 계획되어 있습니다. 그때까지는 '요청'을 직접 사용하세요. 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 형태에서 마이그레이션하려면 video_url 또는 video_file과 함께 X-Api-Key 및 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에 매핑하고 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 '{ ... }'

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 개체를 제거하기 위한 최선의 시도도 이루어집니다.

웹훅

options.callbackUrl이 설정되면 터미널 작업이 사용자 웹훅으로 전송됩니다. options.callbackSecret이 설정된 경우 전송에는 다음이 포함됩니다.

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

이벤트는 job.completed, job.failed, job.canceled입니다.

KIE의 공급자 웹훅은 다음을 대상으로 해야 합니다.

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

프로덕션에서 KIE_WEBHOOK_HMAC_KEY를 설정합니다.

API

On this page