# Skyboxes

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.

# Generate Skybox

Used for generating skyboxes, skybox remixes and depth maps.

# Method

POST

# API Endpoint

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

# Params

Key Data Type Description
prompt String Text prompt describing the skybox world you wish to create. Maximum number of characters: 550. If you are using skybox_style_id then the maximum number of characters is defined in the max-char response parameter defined for each style required
negative_text String Describe things to avoid in the skybox world you wish to create. Maximum number of characters: 200. If you are using skybox_style_id then the maximum number of characters is defined in the negative-text-max-char response parameter defined for each style optional
enhance_prompt Boolean Have an AI automatically improve your prompt to generate pro-level results every time (default: false) optional
seed Int Send 0 for a random seed generation. Any other number (1-2147483647) set will be used to "freeze" the image generator and create similar images when run again with the same seed and settings. optional
skybox_style_id Int Predefined styles that influence the overall aesthetic of your skybox generation (Fantasy landscape, Anime art style, etc...). Explained in more detail here. optional
remix_imagine_id Int ID of a previously generated skybox. optional
control_image Binary
or
Base64 string
or
Absolute URL
Control image used to influence the generation. The image needs to be exacly 1024 pixels wide and 512 pixels tall PNG equirectangular projection image of a sketch with black (#00000) background and white (#ffffff) brush strokes. For "sketch" effect you will also need to send control_model="sketch". optional
control_model String Model used for the control_image. Currently the only option is: "sketch". optional
return_depth_hq Boolean Request for high quality depth map. It will be returned in the depth_map_url parameter. (default: false) optional
webhook_url String Optionally, you may specify a webhook url to specify the destination for progress updates optional
init_image Binary
or
Base64 string
or
Absolute URL
Image to be used as initial image for Skybox generation. Please use equirectangular 360° images. 2:1 aspect ratio recommended. Maximum file size is 50 megabytes. Check the example and best practices for more details. optional
init_strength Float Scale to be used as initial influence of the "Init Image" for Skybox generation. The default value is 0, allowed range is between 0 and 0.97, where 0 represents no influence and 0.97 represents lots of influence. Only has an effect when using an init_image parameter. optional

# Generate skybox request example

To generate a skybox send application/json POST request to https://backend.blockadelabs.com/api/v1/skybox with prompt parameter as a description of the skybox world you wish to create. You can also try our Postman collection to start testing:

Skybox Request

# Response example

{
  "id": 123456, // id of your generation. It can be used to track generation progress or to cancel the generation
  "skybox_style_id": 2, // skybox style id used in a generation request
  "skybox_style_name": "Fantasy Landscape", //skybox style name used in a generation request
  "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.
  "type": "skybox", // type of skybox generation
  "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
}

TIP

Don't forget that after you receive the response above you need to track generation progress.

# Status update message example:

{
  "id": 123456,
  "obfuscated_id": "460370b7328a5cb8dbddd6ef0d1c9dd4",
  "skybox_style_id": 2,
  "skybox_style_name": "Fantasy Landscape",
  "status": "complete",
  "queue_position": 1,
  "file_url": "https://blockade-platform-production.s3.amazonaws.com/images/imagine/detailed_digital_painting_cd_computer_render_fantasy_vr_dreamscape__6fee994c6f9f2229__793071_6.jpg?ver=1",
  "thumb_url": "https://blockade-platform-production.s3.amazonaws.com/thumbs/imagine/thumb_detailed_digital_painting_cd_computer_render_fantasy_vr_dreamscape__6fee994c6f9f2229__793071_6.jpg?ver=1",
  "depth_map_url": "https://blockade-platform-production.s3.amazonaws.com/depths/imagine/detailed_digital_painting_cd_computer_render_fantasy_vr_dreamscape__6fee994c6f9f2229__793071_6.jpg?ver=1",
  "title": "Imagination #123456",
  "user_id": 1,
  "username": "user@blockadelabs.com",
  "error_message": null,
  "pusher_channel": "status_update_460370b7328a5cb8dbddd6ef0d1c9dd4",
  "pusher_event": "status_update",
  "created_at": "2023-03-18T10:42:19+00:00",
  "updated_at": "2023-03-18T10:42:36+00:00"
}

# Generate Skybox Examples

Use the following examples as a request parameters for the generate skybox API request:
POST https://backend.blockadelabs.com/api/v1/skybox

# Generate Skybox using the "Digital Painting" style

{
  "prompt": "prompt example",
  "skybox_style_id": 5, // "digital painting" skybox style id
}

# Remix previously generated skybox

{
  "prompt": "prompt example",
  "skybox_style_id": 5, // "digital painting" skybox style id
  "remix_imagine_id": 123456 // id of a previously generated skybox
}

# Remix from uploaded (equirectangular) image

{
  "prompt": "prompt example",
  "skybox_style_id": 5, // "digital painting" skybox style id
  "init_image": "https://images.blockadelabs.com/skybox-starters/42_133ff00e73def7ca30c01b24be7991d9_file.jpg", // this parameter can be sent as Binary, Base64 string or Absolute URL string
  "init_strength": 0.75
}
# Best practices

The init_image should be an equirectangular image sent across as binary, base64 or absolute URL with a common resolution of 2048x1024 or greater, with an aspect ratio of 2:1 and a max file size of 50MB. Images submitted outside of the aspect ratio of 2:1 will be forced to a 2:1 ratio during processing which could produce undesired image warping. If no image is submitted as init_image, then the parameter of init_strength defaults to 0.0 and the normal processing will take place.

The init_strength is a value that operates within the process that an image overrides diffusion and the remainder will generate new content.

Example: a value of 0.1 will take the submitted image into consideration for only 10% of the process, and then normal diffusion will begin to add new content based on the prompt provided. A value of 0.75 will use the submitted image for 75% of the process, skipping over most of the diffusion process and yielding an outcome that more closely resembles the original. The maximum allowed value for init_strength is 0.97 which allows for minimum change and near-zero diffusion. Values higher than 0.97 will return an error and the content will not process.

Some submitted images and prompts will produce varied results and thus there is no best value to use when adjusting init_strength. For testing, it is recommended to start with a value of 0.5 for init_strength and observe the outcome - lowering or raising the value for desired diffusion.

If an image is submitted with init_image parameter, yet init_strength is not defined, the result will assume a value of 0.0 and return an output unrelated to the init_image. A user must set a value above 0.0 for init_strength for their init_image to be considered as part of the output content

# Generate Skybox using sketch control image

{
  "prompt": "prompt example",
  "skybox_style_id": 5, // "digital painting" skybox style id
  "control_image": "https://images.blockadelabs.com/images/control_images/vr02abXGRh7xTfLblvVytKFjKGE0AKxoEe8jDQuc.png", // this parameter can be sent as Binary, Base64 string or Absolute URL string
  "control_model": "sketch"
}

# Get Skybox Styles

Returns the list of predefined styles that can influence the overall aesthetic of your skybox generation.

# Method

GET

# API Endpoint

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

# Response example

[
    {
        "id": 2, // to be used as 'skybox_style_id' parameter in the 'Generate skybox' endpoint to influence the overall aesthetic of your skybox generation
        "name": "Fantasy Landscape", // name of the style
        "max-char": 390, // maximum number of characters that can be used for 'prompt' in the 'Generate skybox' endpoint
        "negative-text-max-char": 250, // maximum number of characters that can be used for 'negative_text' in the 'Generate skybox' endpoint
        "image": "https://blockade-platform-production.s3.amazonaws.com/thumbs/imagine/thumb_detailed_digital_painting_cd_computer_render_fantasy_vr_dreamscape__6fee994c6f9f2229__793071_6.jpg", // image example of the style
        "sort_order": 1, // sorting order
        "premium": 1
    },
    {
        "id": 3,
        "name": "Anime art style",
        "max-char": 360,
        "negative-text-max-char": 220,
        "image": "https://blockade-platform-production.s3.amazonaws.com/thumbs/imagine/thumb_beautiful_anime_illustration_vr_view_anime_cinematic_lighting__d8f7004caba3e61c__863995_d8f700.jpg",
        "sort_order": 2,
        "premium": 0
    },
    ...
]

# Get Skybox Style Families

Returns the list of predefined styles that can influence the overall aesthetic of your skybox generation, sorted by style family. This route can be used in order to build a menu of styles sorted by family.

# Method

GET

# API Endpoint

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

# Response example

[
    {
        "type": "family", // can be of type 'family' or 'style' if the style doesn't belong to any families
        "id": 1, // id of a type
        "name": "Realistic", // name of the menu item 
        "sort_order": 1, // ascending order position in the menu
        "items": [
            {
                "type": "style", // refers to a skybox style type found within a specific family
                "id": 9, // to be used as 'skybox_style_id' parameter in the 'Generate skybox' endpoint to influence the overall aesthetic of your skybox generation
                "name": "Realism", // name of the style
                "sort_order": 1, // ascending order position inside a family
                "description": "All kinds of photographic worlds rendered in realistic tones and textures", // This is a description of this style (string/nullable)
                "max-char": 381, // maximum number of characters that can be used for 'prompt' in the 'Generate skybox' endpoint
                "negative-text-max-char": 180, // maximum number of characters that can be used for 'negative_text' in the 'Generate skybox' endpoint
                "image": "https://images.blockadelabs.com/images/skybox/wubz1SlOJMGQgGvqFjsxoJBGY1pJkGPd79XDwfFf.webp", // webp image example of the style
                "image_jpg": "https://images.blockadelabs.com/images/skybox/wubz1SlOJMGQgGvqFjsxoJBGY1pJkGPd79XDwfFf.jpg", // jpg image example of the style
            },
            {
                "type": "style", 
                "id": 6,  
                "name": "Radiant Realism",
                "sort_order": 2, 
                "description": "Photographic natural landscapes with extra emphasis on beautiful lighting.", 
                "max-char": 332, 
                "negative-text-max-char": 180,
                "image": "https://images.blockadelabs.com/images/skybox/9cIguHL6DgS4TyCdG9GTzoxM7ho0N5Vd9lPjkh2s.webp",
                "image_jpg": "https://images.blockadelabs.com/images/skybox/9cIguHL6DgS4TyCdG9GTzoxM7ho0N5Vd9lPjkh2s.jpg",
            },
            ...
        ]
    },
    {
        "type": "style",
        "id": 13,
        "name": "Advanced (no style)",
        "sort_order": 9,
        "description": null,
        "max-char": 540,
        "negative-text-max-char": 220,
        "image": null,
        "image_jpg": null,
    }
]

# Get Skybox by id

# Method

GET

# API Endpoint

https://backend.blockadelabs.com/api/v1/imagine/requests/{id}

# Response example

{
  "request" : {
    "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 (currently "skybox" is the only one)
    "title": "Imagination #123456", // generation title
    "prompt": "prompt text", // prompt text used to generate skybox
    "seed": 123456, // seed number 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
    "dispatched_at": "2023-03-18T10:42:20+00:00", // time dispatched
    "processing_at": "2023-03-18T10:42:21+00:00", // time processing started
    "completed_at": "2023-03-18T10:42:39+00:00", // time completed
  }
}

# Get Skybox by Obfuscated id

# Method

GET

# API Endpoint

https://backend.blockadelabs.com/api/v1/imagine/requests/obfuscated-id/{obfuscatedId}

# Response example

{
  "request" : {
    "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 (currently "skybox" is the only one)
    "title": "Imagination #123456", // generation title
    "prompt": "prompt text", // prompt text used to generate skybox
    "seed": 123456, // seed number 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
    "dispatched_at": "2023-03-18T10:42:20+00:00", // time dispatched
    "processing_at": "2023-03-18T10:42:21+00:00", // time processing started
    "completed_at": "2023-03-18T10:42:39+00:00", // time completed
  }
}

# Get History

# Method

GET

# API Endpoint

https://backend.blockadelabs.com/api/v1/imagine/myRequests

# Params

Key Data Type Description
status String Filter by status. Options: all, pending, dispatched, processing, complete, abort, error (default: all) optional
limit Int Number of items to be returned per page (default: 18, max-value: 100) optional
offset Int Page number (default: 0) optional
order String Sort order. Options: ASC, DESC (default: DESC) optional
imagine_id Int Filter by skybox id optional
query String Filter by title or prompt optional
generator String Filter by generator optional

# Response example

{
  "data": [
    {
      "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 (currently "skybox" is the only one)
      "title": "Imagination #123456", // generation title
      "prompt": "prompt text", // prompt text used to generate skybox
      "seed": 123456, // seed number 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
      "dispatched_at": "2023-03-18T10:42:20+00:00", // time dispatched
      "processing_at": "2023-03-18T10:42:21+00:00", // time processing started
      "completed_at": "2023-03-18T10:42:39+00:00", // time completed
    }
  ],
  "totalCount": 1,
  "has_more": false
}

# Cancel Generation

# Method

DELETE

# API Endpoint

https://backend.blockadelabs.com/api/v1/imagine/requests/{id}

TIP

This request sets the status to the abort value.


# Response example

{
  "success": true
}

# Cancel All Pending Generations

This request sets the status of all pending generations to abort.

# Method

DELETE

# API Endpoint

https://backend.blockadelabs.com/api/v1/imagine/requests/pending

# Response example

{
  "success": true
}

# Delete

This request deletes skybox.

# Method

DELETE

# API Endpoint

https://backend.blockadelabs.com/api/v1/imagine/deleteImagine/{id}

# Response example

{
  "success": "Item deleted successfully",
  "id": "42"
}