Blockade Labs API Documentation

# Getting Started

Hello! We are here to assist you in navigating the exciting world of Blockade Labs API and to make your experience in creating breathtaking skyboxes for your digital applications as accessible and enjoyable as possible. Let's embark on this journey together, step by step. 🚀

# API Key

First things first, you'll need an API Key to get started. If you don't have one please go to https://api.blockadelabs.com and apply for one.

It is not advisable to expose your API Key on the frontend of your application. Rather, it is recommended to use one of the SDK Libraries we have prepared for you or develop your own backend service for communication with frontend application, and subsequently utilize server-to-server requests to access the Blockade Labs API endpoints.

# Making Requests

It is essential that your API key is included in the HTTP Request Header as x-api-key parameter:

Key Value
x-api-key 7J7eD5TIiJR4Gky...

Optionally, you can send it as url query parameter api_key (this method is less secure): https://backend.blockadelabs.com/api/v1/skybox?api_key=7J7eD5TIiJR4Gky...

Depending on your preference for POST requests you can send parameters and values as JSON (application/json) or FormData (multipart/form-data). Be aware that if you are using JSON you will need to encode the file you want to upload in base64 format.


# Sending Your First Skybox Request

All you need to do is send a POST request to https://backend.blockadelabs.com/api/v1/skybox with prompt parameter:

{
  "prompt": "prompt example" // Text prompt describing the skybox world you wish to create 
}

# 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": "World #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. By utilizing one of the official Pusher libraries you can seamlessly integrate it into your application. 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.

You can test webhooks by using https://webhook.site/

# 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. Explained here in more detail.

# 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 (currently "skybox" is the only one)
  "title": "Imagination #123456", // generation title
  "prompt": "prompt text", // prompt text used to generate skybox
  "skybox_style_id": 10, // skybox style id used to generate skybox
  "skybox_style_name": "SciFi", // skybox style name used to generate skybox
  
  "file_url": "https://blockade-platform-production.s3.amazonaws.com/images/imagine/futuristic_microdetailed_vr_scifi_concept_art_cinematic_vr_neon__dbe7f963dc23699c__2757929_dbe7.jpg?ver=1", // generated skybox image (6144x3072 pixels)
  "thumb_url": "https://blockade-platform-production.s3.amazonaws.com/thumbs/imagine/thumb_futuristic_microdetailed_vr_scifi_concept_art_cinematic_vr_neon__dbe7f963dc23699c__2757929_dbe7.jpg?ver=1", // generated skybox thumbnail (672x336 pixels)
  "depth_map_url": "https://blockade-platform-production.s3.amazonaws.com/depths/imagine/futuristic_microdetailed_vr_scifi_concept_art_cinematic_vr_neon__dbe7f963dc23699c__2757929_dbe7.jpg?ver=1", // generated skybox depyh 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

For a seamless testing experience, feel free to use our Postman collection to test all our available API endpoints.

# That's it!

Please don't hesitate to reach out to us via email at support@blockadelabs.com or through our Discord server's dedicated #support channel should you have any further inquiries or concerns.

Skyboxes →