# Skyboxes

Auth: Getting started · Security.

To queue multiple skyboxes in one request, see Skybox Batches.

# Generate Skybox

To generate a skybox, select a style and pass its id as skybox_style_id. Styles select the model (Model 2 is deprecated; Model 3 is widespread; Model 4 is latest quality).

Native resolution: Model 2/3 default 8K; Model 4 is 4K. Other formats and resolutions: Skybox Exports.

# Model 4

Same POST /api/v1/skybox endpoint as Model 3. Point skybox_style_id at a Model 4 style and send variant_id (Balance 1, Detail 2). There is no separate Model 4 URL.

prompt, negative_text, and enhance_prompt are the same fields on both models. Character limits come from that style’s max-char and negative-text-max-char. Remix fields are in the table below. On Model 4 the source is read as Depth or Softlines (soft_lines). init_strength is the Model 3 color dial. horizon_shift (−20 to 20) is a Model 4 parameter. It is not used for Model 3 generations.

A completed generation includes file_url, thumb_url, and depth_map_url. History items include thumb_url. Native output is 4K. Exports: Skybox exports.

The same seed with the same settings produces a similar image. variant_id is a setting, so Balance and Detail are separate runs.

Credit costs by variant: Quality.

Plan access: Model 4 styles and quality variants (variant_id Balance or Detail) require a Standard or Business plan. Essential and Free plans cannot use Model 4 (the API returns 403 Access denied).

Edit (Add/Remove): send center_x, center_y, and fov together to run an edit on an existing skybox (or starter). Requires a Model 4 skybox_style_id, a source (edit_skybox_id) skybox, and costs 1 credit. variant_id is not allowed for edit. The source image may be from any model; only the style used for the edit must be Model 4.

Image2Pano (Convert): send image_to_pano_init_image (or image_to_pano_init_image_hash) to convert a photo into a skybox. Requires a Model 4 skybox_style_id and costs 3 credits (Balance). variant_id is not allowed.

# Method

POST

# API Endpoint

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

# Params

Key Data Type Description
skybox_style_id Int Predefined styles are used to choose the model version and influence the overall aesthetic of your skybox generation (Fantasy landscape, Anime art style, etc...). Explained in more detail here. For edit and Image2Pano, must be a Model 4 style. required
prompt String Text prompt describing the skybox world you wish to create. Maximum number of characters: 2000. 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: 600. 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
horizon_shift Int Model 4 only. Defaults to 0. Accepted values vary from -20 to 20. Negative shifts horizon down, positive shifts up. Use cases: ground-heavy scenes (positive value), sky-dominant scenes (negative value), fixing equator seams (±5-10). Not used for Model 3 generations. optional
variant_id Int ID of a generation quality variant, from the variants array returned by the Get Skybox Styles endpoint. If omitted, the default variant for the style is used automatically. Use the variant ID to influence the overall quality (and speed) of your skybox generation. For example, if you used variant_id of 2 (Detail variant) the quality of the skybox generation would be higher but it would also take more time to produce it. Not allowed for edit or Image2Pano. optional
soft_lines Boolean Only applicable to Model 4 styles. Enables softer line rendering while preserving structural geometry (retains structure). When true, remix uses the Softlines path. When false (default), remix uses the Depth path. Web: Retain Structure maps to soft_lines: true. Use Softlines when Depth is holding edges or rough geometry too tightly. Web how-to: Remix. optional
remix_imagine_id Int ID of a previously generated skybox to remix. The skybox_style_id you send chooses the model that runs. optional
remix_collection_id Int Project ID from the web app. Each request picks a random completed skybox from that Project. optional
control_image Binary
or
Base64 string
or
Absolute URL
Equirectangular control image. On Model 4 this is the Depth or Softlines path. Send control_model "remix". optional
control_image_hash String obfuscated_id of a skybox that already has a control image, instead of uploading the file again. optional
control_model String Model used for control_image. The only value is "remix". optional
init_image Binary
or
Base64 string
or
Absolute URL
Equirectangular init image. Granular strength is a Model 3 control. optional
init_image_hash String obfuscated_id of a skybox that already has an init image, instead of uploading the file again. optional
init_strength Float Model 3 color dial. Inverted scale from 0.11 (strong) to 0.9 (weak). Required with init_image, or that image is ignored. optional
seed Int Send 0 for a random seed generation. Any other number (1-4294967295) set will be used to "freeze" the image generator and create similar images when run again with the same seed and settings. variant_id is one of those settings. optional
edit_skybox_id Int ID of the previously generated skybox that is used as a starting point for edit functionality. Check the example here. required for edit
center_x Int Horizontal center of the edit region (e.g. 2048). Required for edit together with center_y and fov. Range: 0-4096. required for edit
center_y Int Vertical center of the edit region (e.g. 1024). Required for edit together with center_x and fov. Range: 0-2048. required for edit
fov Int Field of view of the edit region (e.g. 70). Required for edit together with center_x and center_y. Range: 50-90. required for edit
image_to_pano_init_image Binary
or
Base64 string
or
Absolute URL
Photo used for Image2Pano (Convert). Check the example here. required for Image2Pano (or use hash)
image_to_pano_init_image_hash String To be used instead of image_to_pano_init_image to avoid re-uploading. Value is the obfuscated_id (hash ID) from a prior Image2Pano generation that used an init image. optional
webhook_url String Optionally, you may specify a webhook url to specify the destination for progress updates optional
max_wait Int Maximum number of seconds to wait for the generation to complete. If the generation does not complete within this time, it will be set to error status and credits will be refunded. Accepted range: 30-1800 seconds. Recommended to set higher than the estimated latency for your chosen variant (see the Model 4 estimated latency details below). optional

Shift Horizon

Usage of the horizon_shift param:

  • Ground-heavy scenes (landscapes, terrain) — positive value raises horizon, gives more sky
  • Sky-dominant scenes (Sky Dome, flight sim) — negative value lowers horizon, expands sky
  • Fixing equator seams — small adjustments (±5) can help blend ground/sky transitions

In the web app this control is Shift Horizon, under Remix settings for Model 4. It does not appear for Model 3. Remix source fields (remix_imagine_id, remix_collection_id, control image, init image) are accepted on both models, and the path differs: Model 4 follows Depth or Softlines (soft_lines), and init_strength is the Model 3 color dial. Web: Model 3 and Model 4.


Based on the variant you select for Model 4, generation time and quality change. Credits, latency, and a recommended max_wait timeout:

Variant Variant ID Credits Est. Latency Recommended Timeout
Balance 1 3 ~60s 120s
Detail 2 6 ~120s 240s
Edit n/a 1 ~10s 20s
Image2Pano n/a 3 ~95s 190s

Plan comparison: Pricing and limits. Concurrency and pending limits: Pricing and limits.

Apps that need a result by a deadline should send max_wait (seconds). Timed-out jobs go to error and credits are refunded. Handle that in the product; do not spin forever. In your app.

# Model 3

Model 3 and Model 4 styles use the same endpoint. Model 2 is deprecated. Model 3 is the Fast production model. No Model 3 retirement date is published here.

Model 3 generations are Fast and will always deduct 1 credit.

# Method

POST

# API Endpoint

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

# Params

Key Data Type Description
skybox_style_id Int Predefined styles are used to choose the model version and influence the overall aesthetic of your skybox generation (Fantasy landscape, Anime art style, etc...). Explained in more detail here. required
prompt String Text prompt describing the skybox world you wish to create. Maximum number of characters: 2000. 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: 600. 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
remix_imagine_id Int ID of a previously generated skybox. Check the example here. optional
remix_collection_id Int ID of a Project (collection) created in the web app. Each request picks a random completed skybox from that Project as the remix source — useful for apps that curate scene references and want consistent-but-varied programmatic generations. Example: Remix from a Project. optional
control_image Binary
or
Base64 string
or
Absolute URL
Control image used to influence the generation (ie. remix from control image). Explained in more detail here. optional
control_image_hash String To be used instead of the control_image param in order to avoid uploading the same file each time. The value of the param should be an obfuscated_id (hash ID) of an already generated skybox which used a control image. The control image of that existing skybox will be used for subsequent generations. optional
control_model String Model used for the control_image. Currently the only option is: "remix". optional
init_image Binary
or
Base64 string
or
Absolute URL
Init image used to influence the generation (ie. remix from init image). Explained in more detail here. optional
init_image_hash String To be used instead of the init_image param in order to avoid uploading the same file each time. The value of the param should be an obfuscated_id (hash ID) of an already generated skybox which used an init image. The init image of that existing skybox will be used for subsequent generations. optional
init_strength Float Scale to be used as initial influence of the "Init Image" for Skybox generation. It uses an inverted scale. Allowed range is between 0.11 and 0.9, where 0.11 represents lots of influence, and 0.9 represents no influence. Only has an effect when using an init_image parameter. optional
webhook_url String Optionally, you may specify a webhook url to specify the destination for progress updates optional
max_wait Int Maximum number of seconds to wait for the generation to complete. If the generation does not complete within this time, it will be set to error status and credits will be refunded. Accepted range: 30-1800 seconds. Recommended to set higher than the estimated latency (see the Model 3 estimated latency details below). optional

Additional details for Model 3 regarding cost, estimated generation time, and recommended timeouts. Typical times match Quality.

Credits Est. Latency Recommended Timeout
1 ~15s 60s

Apps that need an output by a deadline

Set max_wait to the seconds your user can wait. If the job does not complete, status becomes error and credits are refunded. Errors.

# 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": 155, // skybox style id used in a generation request
  "skybox_style_name": "Open World", //skybox style name used in a generation request
  "variant_id": 1, // variant id used for generation (only present for Model 4 generations; omitted for edit)
  "credit_cost": 3, // credits charged (1 for edit, otherwise the selected variant cost)
  "model": "Model 4", // model used to generate
  "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", // "skybox", "skybox remix", or "skybox edit"
  "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": "Generation #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
}

Edit responses additionally include center_x, center_y, fov, and edit_skybox_id. Type is "skybox edit" and credit_cost is 1.

Image2Pano responses additionally include image_to_pano_init_image_hash. Type is "skybox image to pano" and credit_cost is 3.

Wait for completion

After this response, wait for completion: Wait for completion.

# Generation progress - Status update message example:

{
  "id": 123456,
  "obfuscated_id": "460370b7328a5cb8dbddd6ef0d1c9dd4",
  "skybox_style_id": 155,
  "skybox_style_name": "Open World",
  "variant_id": 1, // variant id used for generation (only present for Model 4 generations)
  "model": "Model 4",
  "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": "Generation #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"
}

# Error Responses

Full status table, including edit and Image2Pano: Errors. Pending limits: Pricing and limits.

Common codes: 403 plan/permission, 404 missing style or hash, 422 invalid body, 429 pending limit, 500/503 service issues.

# 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 "Open World" style (Model 4)

{
  "skybox_style_id": 155, // "Open World" skybox style id
  "prompt": "prompt example"
}

# Generate Skybox using the "Open World" style (Model 4) with a specific quality variant

{
  "skybox_style_id": 155, // "Open World" skybox style id
  "prompt": "mountains",
  "variant_id": 2 // use the "Detail" quality variant; get variant ids from the Get Skybox Styles response
}

# Generate Skybox using the "Open World" style (Model 4), with negative text, horizon_shift, variant_id, seed, prompt enhancer and webhook_url

{
  "skybox_style_id": 155, // "Open World" skybox style id
  "prompt": "mountains", // when enhance_prompt is sent this text will be used by AI to improve it
  "negative_text": "clouds, river", // avoid generating clouds and river
  "horizon_shift": 5, // shift the horizon line up from the center
  "enhance_prompt": true, // automatically improve the prompt
  "variant_id": 2, // use Detail quality variant
  "seed": 234143, // set generation seed number
  "webhook_url": "https://www.example.com/webhook" // the url destination where the progress updates should be sent
}

# Edit an existing skybox (Model 4)

{
  "skybox_style_id": 155, // must be a Model 4 style
  "prompt": "add wooden bridge",
  "negative_text": "cars, people", // optional
  "edit_skybox_id": 123456, // id of a previously generated skybox
  "center_x": 2048,
  "center_y": 1024,
  "fov": 70
}

# Image2Pano - convert a photo to a skybox (Model 4)

{
  "skybox_style_id": 155, // must be a Model 4 style
  "prompt": "snowy mountain landscape",
  "negative_text": "people, cars", // optional
  "image_to_pano_init_image": "https://example.com/photo.jpg" // Binary, Base64 string, or Absolute URL
}

# Generate Skybox using the "Cyberpunk" style (Model 3)

{
  "skybox_style_id": 90, // "Cyberpunk" skybox style id
  "prompt": "prompt example"
}

# Generate Skybox using the "Cyberpunk" style (Model 3), with negative text, seed, prompt enhancer and webhook_url

{
  "skybox_style_id": 90, // "Cyberpunk" skybox style id
  "prompt": "mountains", // when enhance_prompt is sent this text will be used by AI to improve it
  "negative_text": "clouds, river", // avoid generating clouds and river
  "enhance_prompt": true, // automatically improve the prompt
  "seed": 234143, // set generation seed number
  "webhook_url": "https://www.example.com/webhook" // the url destination where the progress updates should be sent
}

# Remix previously generated skybox (Model 3)

{
  "skybox_style_id": 90, // "Cyberpunk" skybox style id
  "prompt": "prompt example",
  "remix_imagine_id": 123456 // id of a previously generated skybox
}

# Remix using a random skybox from a previously created project (Model 3 / Model 4)

Curate a Project of scene references in the web app, then pass its ID as remix_collection_id. Each generate samples a random completed skybox from that collection as the remix source.

{
  "skybox_style_id": 90, // "Cyberpunk" skybox style id
  "prompt": "prompt example",
  "remix_collection_id": 123456 // id of a previously created project
}

# Remix from uploaded (equirectangular) image - Control image (Model 3)

{
  "skybox_style_id": 90, // "Cyberpunk" skybox style id
  "prompt": "prompt example",
  "control_image": "https://images.blockadelabs.com/skybox-starters/42_133ff00e73def7ca30c01b24be7991d9_file.jpg", // this parameter can be sent as Binary, Base64 string or Absolute URL string
  "control_model": "remix" // required parameter in order for "remix from control image" to work
}
# Remix from Control Image - Best practices

Keeps shape and structure, not colors. Web how-to: Remix.

Always include control_model with value remix. Equirectangular source, 2:1 aspect, about 2048×1024 or larger, max 50MB.

Public Model 4 starters are equirectangular JPGs. Send one as control_image. The library, and this request explained, is on Gallery starters.

{
  "skybox_style_id": 155, // "Open World" (Model 4)
  "prompt": "The same woodland at foggy dawn, orange sun gone, cool mist between the trees.",
  "negative_text": "people",
  "control_image": "https://images.blockadelabs.com/skybox-starters/158_3ab4125d980b3a20f922699b0d30b812_file.jpg", // Eucalyptus bushfire haze starter
  "control_model": "remix",
  "soft_lines": true, // Softlines / Retain structure. false is Depth
  "variant_id": 1 // Balance
}

# Remix from uploaded (equirectangular) image - Init image (Model 3)

{
  "skybox_style_id": 90, // "Cyberpunk" skybox style id
  "prompt": "prompt example",
  "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.5
}
# Remix from Init image - Best practices

Keeps colors and composition as a starting point. Web how-to: Remix.

Set init_strength between 0.11 and 0.9 when you send init_image (start at 0.5). If init_strength is omitted, the init image is ignored. Granular strength is most reliable on Model 3 styles.

# Get Skybox Styles

This endpoint returns a list of predefined styles that shape the overall aesthetic of your skybox generation.

Each style in the response includes model and model_version parameters, indicating the model that will be used for generation. Since Model 2 is deprecated, ensure you request this endpoint with the model_version parameter set to 3 or 4. Model 3 is our standard widespread model and Model 4 comes with the latest quality improvements. Model 4 styles require a Standard or Business plan (Essential and Free cannot use them).

Bear in mind that Model 4 styles have variants that affect the quality, speed, and credit cost of the generations. Check the variants array in the response example for more details. Models 2 and 3 don't have variants and will always consume 1 credit.

Credit amounts: Quality. Prompt shape: Prompting.

For example: https://backend.blockadelabs.com/api/v1/skybox/styles?model_version=4.

# Method

GET

# API Endpoint

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

# Params

Key Data Type Description
model_version String Filter skybox styles by model version number. Since model 2 is now deprecated use either 3 or 4 as the version. optional

# Response example

[
    {
        "id": 90, // to be used as 'skybox_style_id' parameter in the 'Generate skybox' endpoint to influence the overall aesthetic of your skybox generation
        "name": "Cyberpunk", // 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
        "model": "Model 3", // model name
        "model_version": "3", // model version number
        "variants": [] // array of quality variants; always empty for Model 3 styles
    },
    {
        "id": 155,
        "name": "Open World",
        "max-char": 1000,
        "negative-text-max-char": 400,
        "image": "https://blockade-platform-production.s3.amazonaws.com/thumbs/imagine/thumb_detailed_digital_painting_cd_computer_render_fantasy_vr_dreamscape__6fee994c6f9f2229__793071_6.jpg",
        "sort_order": 18,
        "model": "Model 4",
        "model_version": "4",
        "variants": [ // quality variants available for this style; use the 'id' as 'variant_id' when generating a skybox
            {
                "id": 1, // to be used as 'variant_id' parameter in the 'Generate skybox' endpoint to influence the overall quality of your skybox generation
                "label": "Balance", // was Standard
                "key": "balance",
                "credit_cost": 3, // number of skybox credits deducted per generation with this variant
                "is_default": true // default variant, used when variant_id is not specified
            },
            {
                "id": 2,
                "label": "Detail", // was Enhanced
                "key": "detail",
                "credit_cost": 6,
                "is_default": false
            }
        ]
    },
    ...
]

# 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": "Generation #123456", // generation title
    "prompt": "prompt text", // prompt text used to generate skybox
    "seed": 123456, // seed number 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
    "model": "Model 4", // model name used to generate skybox
    "variant_id": 1, // variant id used for generation (Model 4 only)
    
    "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", // native skybox image (Model 3: 8192x4096, Model 4: 4096x2048)
    "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 (720x360 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 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
    "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": "Generation #123456", // generation title
    "prompt": "prompt text", // prompt text used to generate skybox
    "seed": 123456, // seed number 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
    "model": "Model 4", // model name used to generate skybox
    "variant_id": 1, // variant id used for generation (Model 4 only)
    
    "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", // native skybox image (Model 3: 8192x4096, Model 4: 4096x2048)
    "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 (720x360 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 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
    "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 Number of records to skip (page index × limit; 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
variant_id Int Filter by variant ID (from the variants array in the Get Skybox Styles response) optional
api_key_id Integer Filter by API key ID 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": "Generation #123456", // generation title
      "prompt": "prompt text", // prompt text used to generate skybox
      "seed": 123456, // seed number 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
      "model": "Model 4", // model name used to generate skybox
      "variant_id": 1, // variant id used for generation (Model 4 only)
      
      "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", // native skybox image (Model 3: 8192x4096, Model 4: 4096x2048)
      "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 (720x360 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 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
      "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}

Cancel

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"
}