Blockade Labs API Documentation

# Getting Started

Use the Blockade Labs API to generate skyboxes for games, VR, and other 3D applications.

# API Key

You need an API key to call the API. Create one at skybox.blockadelabs.com/api (opens new window).

Do not expose your API key in frontend code. Call the API from a backend service, or use one of the SDK libraries.

# Making Requests

Send the API key in the x-api-key HTTP header:

Header Value
x-api-key {YOUR_API_KEY}

You can also send it as the api_key query parameter. That is less secure (keys leak into logs and browser history): https://backend.blockadelabs.com/api/v1/skybox?api_key={YOUR_API_KEY}

POST bodies can be JSON (application/json) or FormData (multipart/form-data). If you use JSON and upload a file, encode the file as base64.

# Sending Your First Skybox Request

Send a POST to https://backend.blockadelabs.com/api/v1/skybox with a style ID and a prompt. Get style IDs from Get Skybox Styles. skybox_style_id is required.

TIP

Comments inside JSON examples are for explanation only. Strip them before sending the request.

{
  "skybox_style_id": 155,
  "prompt": "prompt example"
}

# Response example

{
  "id": 123456, // id of your generation. It can be used to track generation progress or to cancel/delete the generation
  "status": "pending", // initially status is set as 'pending' after you send a generation request. Status will change from one state to another and you will get updates for each one if you are using pusher or webhook: pending -> dispatched -> processing -> complete. Also you can get abort or error.
  "queue_position": 2, // position of your request in a generation queue
  "file_url": "", // full size of generated image url (empty until generation is completed)
  "thumb_url": "", // thumbnail of generated image url (empty until generation is completed)
  "title": "Imagination #123456", // generation title
  "user_id": 1, // your user id
  "username": "user@blockadelabs.com", // your username
  "error_message": null, // if status=error here you should see the error message
  "obfuscated_id": "460370b7328a5cb8dbddd6ef0d1c9dd4", // hash id of your generation
  "pusher_channel": "status_update_460370b7328a5cb8dbddd6ef0d1c9dd4", // pusher channel name used to track generation progress
  "pusher_event": "status_update", // pusher channel event used to track generation progress
  "created_at": "2023-03-18T10:42:19+00:00", // time created
  "updated_at": "2023-03-18T10:42:19+00:00" // time updated
}

After obtaining the response, it is necessary to wait for the generator to process the image.

# Tracking Generation Progress

While the image is being generated the status parameter will change in the following order until completion:

  • pending - The generation is in the queue (initial state)
  • dispatched - The generation was sent to the AI workers
  • processing - AI worker started generating
  • complete - The generation has completed and you can retrieve your generated skybox image
  • abort - The generation was aborted
  • error - There has been an error while generating. You can check error_message parameter for more details.

Whenever a status change occurs, a corresponding event message will be dispatched through Pusher (or optionally via webhook).

To track generation progress there are three options:

# 1. Pusher

This is the recommended method to track progress of your generations. Use one of the official Pusher libraries (opens new window) to subscribe to status events. Upon sending a skybox or imagine generation request you will get pusher_channel and pusher_event in the response which can be used to track generation progress.

Pusher parameters:

app_id = "1555452"
key = "a6a7b7662238ce4494d5"
cluster = "mt1"

Example for channel_name and event_name received in a generation response:

{
  "pusher_channel": "status_update_460370b7328a5cb8dbddd6ef0d1c9dd4",
  "pusher_event": "status_update",
}

# 2. Webhook

Webhooks are notifications sent to a unique URL.

To enable webhook status updates just send an additional webhook_url parameter in the Skybox generation request. On each status update we will send a POST request with a progress update message (json) to the webhook_url you provided.

If a webhook delivery fails (for example a network error or a non-2xx response), the system retries up to 4 times after the initial attempt (5 delivery attempts in total), with incremental backoff:

  • 1 minute after the first failure

  • 5 minutes after the second failure

  • 15 minutes after the third failure

  • 1 hour after the fourth failure

This helps ensure that temporary outages or maintenance on the receiving server do not result in lost updates.

When sending webhooks we include 2 additional headers: x-timestamp and x-signature which you can use to confirm that the webhook was sent recently and that it was sent by us.

Webhook is signed with the API secret from skybox.blockadelabs.com/api (opens new window).

Here is an example of how you might check the timestamp and validate the signature using PHP and Laravel:

$receivedTimestamp = $request->header('X-Timestamp');
$receivedSignature = $request->header('X-Signature');
$body = $request->getContent();

// Check if the timestamp is within 5 minutes
if (abs(time() - (int)$receivedTimestamp) > 300) { // 300 seconds = 5 minutes
    return response()->json(['error' => 'Expired webhook'], 403);
}

// Reconstruct expected signature
$expectedSignature = hash_hmac('sha256', $body, $yourApiSecret);

if (!hash_equals($expectedSignature, $receivedSignature)) {
     return response()->json(['error' => 'Invalid signature'], 403);
}

// proceed with valid signature

Finally, here is how a webhook progress update message might look like:

{
  "id": 123456, // id of your generation. It can be used to track generation progress or to cancel the generation
  "obfuscated_id": "460370b7328a5cb8dbddd6ef0d1c9dd4", // hash id of your generation
  "user_id": 1, // your user id
  "username": "user@blockadelabs.com", // your username

  "status": "complete", // initially status is set as 'pending' after you send a generation request. Status will change from one state to another and you will get updates for each one if you are using pusher or webhook: pending -> dispatched -> processing -> complete. Also you can get abort or error.
  "queue_position": 1, // position of your request in a generation queue
  "pusher_channel": "status_update_460370b7328a5cb8dbddd6ef0d1c9dd4", // pusher channel name used to track generation progress
  "pusher_event": "status_update", // pusher channel event used to track generation progress
  "error_message": null, // if status=error here you should find the error message
  
  "type": "skybox", // type of generation 
  "title": "Imagination #123456", // generation title
  "prompt": "prompt text", // prompt text used to generate skybox
  "skybox_style_id": 155, // skybox style id used to generate skybox
  "skybox_style_name": "Open World", // skybox style name used to generate skybox
  
  "file_url": "https://images.blockadelabs.com/images/imagine/Fantasy_equirectangular-jpg_Lonely_lighthouse_monolithic_aged_5491892424_1426791234.jpg?ver=1", // native skybox image (Model 3: 8192x4096, Model 4: 4096x2048)
  "thumb_url": "https://images.blockadelabs.com/thumbs/imagine/thumb_Fantasy_thumb_Lonely_lighthouse_monolithic_aged_4687322504_1426791234.jpg?ver=1", // generated skybox thumbnail (720x360 pixels)
  "depth_map_url": "https://images.blockadelabs.com/depths/imagine/Fantasy_depth-map-png_Lonely_lighthouse_monolithic_aged_5327042288_1426791234.png?ver=1", // generated skybox depth map image (2048x1024 pixels)
    
  "created_at": "2023-03-18T10:42:19+00:00", // time created
  "updated_at": "2023-03-18T10:42:39+00:00", // time updated
}

You can test webhooks with webhook.site (opens new window).

# 3. API Data Polling

Using this method is not recommended as it could potentially trigger our API rate limiter. It should only be utilized for testing purposes.

Make an API request to GET https://backend.blockadelabs.com/api/v1/imagine/requests/{id} and check for status changes. See Get Skybox by id.

# Status update message example:

{
  "id": 123456, // id of your generation. It can be used to track generation progress or to cancel the generation
  "obfuscated_id": "460370b7328a5cb8dbddd6ef0d1c9dd4", // hash id of your generation
  "user_id": 1, // your user id
  "username": "user@blockadelabs.com", // your username

  "status": "pending", // initially status is set as 'pending' after you send a generation request. Status will change from one state to another and you will get updates for each one if you are using pusher or webhook: pending -> dispatched -> processing -> complete. Also you can get abort or error.
  "queue_position": 1, // position of your request in a generation queue
  "pusher_channel": "status_update_460370b7328a5cb8dbddd6ef0d1c9dd4", // pusher channel name used to track generation progress
  "pusher_event": "status_update", // pusher channel event used to track generation progress
  "error_message": null, // if status=error here you should find the error message
  
  "type": "skybox", // type of generation 
  "title": "Imagination #123456", // generation title
  "prompt": "prompt text", // prompt text used to generate skybox
  "skybox_style_id": 155, // skybox style id used to generate skybox
  "skybox_style_name": "Open World", // skybox style name used to generate skybox
  
  "file_url": "https://images.blockadelabs.com/images/imagine/Fantasy_equirectangular-jpg_Lonely_lighthouse_monolithic_aged_5491892424_1426791234.jpg?ver=1", // native skybox image (Model 3: 8192x4096, Model 4: 4096x2048)
  "thumb_url": "https://images.blockadelabs.com/thumbs/imagine/thumb_Fantasy_thumb_Lonely_lighthouse_monolithic_aged_4687322504_1426791234.jpg?ver=1", // generated skybox thumbnail (720x360 pixels)
  "depth_map_url": "https://images.blockadelabs.com/depths/imagine/Fantasy_depth-map-png_Lonely_lighthouse_monolithic_aged_5327042288_1426791234.png?ver=1", // generated skybox depth map image (2048x1024 pixels)
  
  "created_at": "2023-03-18T10:42:19+00:00", // time created
  "updated_at": "2023-03-18T10:42:39+00:00", // time updated
}

# Postman collection

Use the Postman collection to try the endpoints.

# That's it!

Questions: support@blockadelabs.com or the #support channel in the Blockade Labs Discord (opens new window).

Skyboxes →