# Skybox Batches

All API endpoints require an API Key sent in a header or as a get parameter. Please refer to the Making requests section to find out more.

Batch generation lets you queue multiple skyboxes in a single API request using the same parameters you would send to Generate Skybox (Model 3 or Model 4).

# Plan limits

Batch availability and the maximum total credits per batch request depend on your subscription plan:

Plan	Batch generation	Max credits per batch
Free	Not available	—
Essential	Yes	3
Standard	Yes	3
Business	Yes	30

The per-batch cap is the sum of credits for all skyboxes in the request (quantity × credits per generation). For example, on Essential or Standard you could submit quantity: 3 with Model 3 (1 credit each). On Business, quantity: 30 with Model 3 or quantity: 10 with Model 4 Standard would use the full 30-credit cap.

Free plans receive 403 with message Batch generation is not available on your current plan. If your batch exceeds the plan cap, the API returns 422 explaining the limit.

# Overview

Submit one request with a quantity to create that many skybox generations.
Each skybox in the batch is a normal generation: it has its own ID, status, and Pusher channel. If needed you can track individual generations the same way as a single skybox request (see Tracking generation progress).
The batch object has its own status, counters, and optional webhook_url for batch-level progress updates.
By default, only one batch can be in progress at a time per account. If you submit a new batch while another is still running, the API returns 409.

TIP

Batch submissions bypass the per-account pending generation limit that applies to individual skybox requests, because credit availability is validated for the whole batch before any generations are created.

# Submit Batch

Queue multiple skyboxes with one request.

# Method

POST

# API Endpoint

https://backend.blockadelabs.com/api/v1/skybox/batch

# Params

All parameters supported by Generate Skybox are supported (Model 3 and Model 4), plus:

Key	Data Type	Description
quantity	Int	Number of skyboxes to generate in the batch. Must be a positive integer.	`required`
webhook_url	String	Optional URL to receive batch-level status updates (same payload shape as the batch object).	`optional`

Model 4 batches require variant_id (Standard or Enhanced), the same as a single Model 4 generation.

The total credit cost is quantity × credits per generation. This total must be within your plan's max credits per batch (see Plan limits above) and within your remaining account credits.

# Response example

{
  "id": 42,
  "obfuscated_id": "a1b2c3d4e5f6...",
  "user_id": 1,
  "status": "pending",
  "quantity": 3,
  "successfully_submitted": 3,
  "completed": 0,
  "errored": 0,
  "aborted": 0,
  "pusher_channel": "batch_status_update_a1b2c3d4e5f6...",
  "pusher_event": "status_update",
  "webhook_url": null,
  "submission_errors": [],
  "created_at": "2024-01-01T10:00:00.000000Z",
  "updated_at": "2024-01-01T10:00:00.000000Z",
  "generations": [
    {
      "id": 123456,
      "skybox_style_id": 155,
      "skybox_style_name": "Open World",
      "variant_id": 1,
      "model": "Model 4",
      "status": "pending",
      "type": "skybox",
      "queue_position": 1,
      "file_url": "",
      "thumb_url": "",
      "title": "Imagination #123456",
      "user_id": 1,
      "username": "user@blockadelabs.com",
      "error_message": null,
      "obfuscated_id": "460370b7328a5cb8dbddd6ef0d1c9dd4",
      "pusher_channel": "status_update_460370b7328a5cb8dbddd6ef0d1c9dd4",
      "pusher_event": "status_update",
      "created_at": "2024-01-01T10:00:00+00:00",
      "updated_at": "2024-01-01T10:00:00+00:00"
    }
  ]
}

# Batch status values

Status	Meaning
`pending`	Batch created; one or more generations are still queued or waiting to start.
`dispatched`	At least one generation has been dispatched.
`processing`	At least one generation is actively being processed.
`finalized`	Every generation has finished, and at least one completed successfully.
`error`	Every generation has finished, none completed successfully (there was at least one `error`, other generations are either in `error` or `abort` state).
`abort`	Every generation in the batch was aborted.

Typical progression: pending → dispatched → processing → finalized (when at least one skybox completes).

# Batch response fields

Field	Description
`quantity`	Number of skyboxes requested.
`successfully_submitted`	Number of individual generations that were created and queued.
`completed`	Generations that reached `complete`.
`errored`	Generations that reached `error`.
`aborted`	Generations that reached `abort`.
`submission_errors`	Generations that failed during submit (before being queued). Empty when all generations were accepted.

If some generations fail during submit, successfully queued generations still run. submission_errors lists each failure with index, message, and status. If no generations could be queued, the batch status is set to error.

TIP

Subscribe to the batch pusher_channel with event status_update for batch-level counter and status changes. Each item in generations also has its own pusher_channel for per-skybox updates, identical to a single generation request.

# Error responses

Code	Message (examples)	Cause	Resolution
403	You don't have an active subscription	No usable subscription on the account	Contact Blockade Labs support
403	Batch generation is not available on your current plan.	Batch feature not enabled on your plan	Contact Blockade Labs support
404	Skybox style does not exist	Invalid `skybox_style_id`	Use Get Skybox Styles
409	A batch is already being processed. Please wait for it to complete before submitting a new one.	Another batch is still in progress	Wait for the active batch to finish, or poll Get Batches
422	Quantity must be a positive integer.	Missing or invalid `quantity`	Send a positive integer
422	Batch generation with Model 4 styles requires a Standard or Enhanced variant. Select a variant_id and retry.	Model 4 style without `variant_id`	Send `variant_id` from the style's `variants` array
422	Invalid variant_id: variant not found for this generator.	`variant_id` does not belong to the style's generator	Use a valid variant from Get Skybox Styles
422	Requested quantity of {N} exceeds your plan limit of {M} credits per batch request...	Total batch credit cost exceeds your plan's per-batch cap	Reduce `quantity` or contact support
422	You have {N} credits remaining. This Model 4 batch requires {M} credits...	Not enough credits for a Model 4 batch	Reduce `quantity` or upgrade your plan
422	Model 4 batch generations are not available while you are in overage billing.	Account is in metered/overage mode	Use included credits or contact support
422	You have {N} credits remaining. Generating {Q} skyboxes requires {M} credits.	Not enough credits for the requested batch	Reduce `quantity` or upgrade your plan
503	(varies)	Generations temporarily disabled platform-wide	Try again later

# Get Batches

Returns a paginated list of your batch requests.

# Method

GET

# API Endpoint

https://backend.blockadelabs.com/api/v1/skybox/batch

# Params

Key	Data Type	Description
limit	Int	`optional`, results per page (`1`–`100`, default `18`)
offset	Int	`optional`, page index (multiplied by `limit`; default `0`)
order	String	`optional`, `ASC` or `DESC` (default `DESC`)
status	String	`optional`, filter by batch status (`pending`, `dispatched`, `processing`, `finalized`, `error`, `abort`)
batch_id	Int	`optional`, filter to a specific batch ID

# Response example

{
  "data": [
    {
      "id": 42,
      "obfuscated_id": "a1b2c3d4e5f6...",
      "user_id": 1,
      "status": "finalized",
      "quantity": 3,
      "successfully_submitted": 3,
      "completed": 3,
      "errored": 0,
      "aborted": 0,
      "pusher_channel": "batch_status_update_a1b2c3d4e5f6...",
      "pusher_event": "status_update",
      "webhook_url": null,
      "submission_errors": [],
      "created_at": "2024-01-01T10:00:00.000000Z",
      "updated_at": "2024-01-01T10:05:00.000000Z"
    }
  ],
  "totalCount": 5,
  "has_more": false
}

# Get Batch

Returns one batch with full details for every generation in that batch.

# Method

GET

# API Endpoint

https://backend.blockadelabs.com/api/v1/skybox/batch/{id}

# Params

Key	Data Type	Description
id	Int	Batch ID (path parameter)

# Response example

{
  "id": 42,
  "obfuscated_id": "a1b2c3d4e5f6...",
  "user_id": 1,
  "status": "finalized",
  "quantity": 3,
  "successfully_submitted": 3,
  "completed": 2,
  "errored": 1,
  "aborted": 0,
  "pusher_channel": "batch_status_update_a1b2c3d4e5f6...",
  "pusher_event": "status_update",
  "webhook_url": null,
  "submission_errors": [],
  "created_at": "2024-01-01T10:00:00.000000Z",
  "updated_at": "2024-01-01T10:05:00.000000Z",
  "generations": [
    {
      "id": 123456,
      "obfuscated_id": "460370b7328a5cb8dbddd6ef0d1c9dd4",
      "status": "complete",
      "file_url": "https://blockade-platform-production.s3.amazonaws.com/images/imagine/...",
      "thumb_url": "https://blockade-platform-production.s3.amazonaws.com/thumbs/imagine/...",
      "depth_map_url": "https://blockade-platform-production.s3.amazonaws.com/depths/imagine/...",
      "title": "Imagination #123456",
      "skybox_style_id": 155,
      "skybox_style_name": "Open World",
      "user_id": 1,
      "username": "user@blockadelabs.com",
      "error_message": null,
      "pusher_channel": "status_update_460370b7328a5cb8dbddd6ef0d1c9dd4",
      "pusher_event": "status_update",
      "created_at": "2024-01-01T10:00:00+00:00",
      "updated_at": "2024-01-01T10:02:30+00:00"
    }
  ]
}

# Error responses

Code	Message	Cause
404	Batch not found.	Invalid batch ID, or the batch belongs to another account

← Skyboxes Skybox Exports →