Developer reference

Video API - technical reference

Everything needed to generate a video from your own code: authentication, every endpoint, request and response shapes, error codes, and a full worked example.

← Back to the Video API overview

Getting started

Sign in at bscale.co.il (any BScale account works).
Activate the free Video API module: Settings → Services.
Create an API key in the Video Studio page - shown once, store it safely.
Fund your wallet (Settings → Billing → Top-up). Each generation charges the wallet at the same rates as the in-app studio.

Optional: connect Google Drive to keep every generated video in your Creative Library. Without Drive, finished videos are held for 7 days only - download them via the API.

Authentication

Every call except the signed file download sends the key as a Bearer token:

Authorization: Bearer bsk_live_...

Endpoints

POST	/api/v1/video/generations	Start a generation from a text prompt and, optionally, a reference image. Supports Idempotency-Key to safely retry a request.
GET	/api/v1/video/generations/{id}	Poll status. When succeeded, the response carries a signed videoUrl valid for about an hour.
GET	/api/v1/video/engines	The live engine catalog and price table - which engine, at what length and quality, for how much.
GET	/api/v1/video/files/{id}	The signed download target from videoUrl. No API key needed - the link itself authorizes the download.

Full example

Submit a generation, poll until it finishes, then download the file:

KEY=$BSCALE_API_KEY

# 1. Start a generation
JOB=$(curl -s -X POST https://bscale.co.il/api/v1/video/generations \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{
    "prompt": "A ceramic coffee mug on a rustic wooden table, soft morning light, slow orbit",
    "engine": "ltx",
    "durationSeconds": 5
  }' | jq -r .id)

# 2. Poll every 5-10s until status is "succeeded" or "failed"
watch -n 8 "curl -s https://bscale.co.il/api/v1/video/generations/$JOB \
  -H 'Authorization: Bearer $KEY'"

# 3. Download the finished file (videoUrl is signed, no key needed)
URL=$(curl -s https://bscale.co.il/api/v1/video/generations/$JOB \
  -H "Authorization: Bearer $KEY" | jq -r .videoUrl)
curl -s "$URL" -o video.mp4

Error codes

UNAUTHORIZED	401	Missing, invalid, or revoked API key.
MODULE_NOT_ACTIVE	402	Activate the Video API module in Settings → Services.
INSUFFICIENT_BALANCE	402	Top up the wallet.
VIDEO_DURATION_UNSUPPORTED	400	The chosen duration isn't offered by that engine.
ENGINE_UNAVAILABLE	400	That engine is listed as coming soon.
BAD_REQUEST	400	The reference image couldn't be fetched, or isn't a valid PNG/JPEG/WebP.
VIDEO_NOT_READY	409	The file was requested before generation finished.
IDEMPOTENCY_CONFLICT	409	The same Idempotency-Key is still processing its first call.

Pricing is per generated video, derived from the seconds/quality/engine you choose - see the live table on GET /api/v1/video/engines or the overview page.

Machine-readable schema (OpenAPI JSON)