Blockade Labs API Documentation

# Imagine Requests

These endpoints are intended for the purposes of listing, generating, and managing imagine requests, thereby giving you more control over the image generation process.

# Get Generators

Obtaining a list of available generators and parameters. It is important to know that generator parameter is required to send Generate imagine requests.

# Method

GET

# API Endpoint

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

# Params

Key Data Type Description
api_key String Your API Key required

# Response

[
    {
        "id": 13, 
        "generator": "stable-skybox", // to be used as 'generator' parameter in the 'Generate imagine' endpoint
        "name": "Stable Diffusion Skybox",
        "label": "Stable Diffusion Skybox",
        "params": {
            "prompt": { // to be used as `prompt` parameter in the 'Generate imagine' endpoint
                "name": "Text Prompt", // name of the parameter
                "type": "textarea", // parameter data type
                "required": true, // defines if the parameter is required
                "max_value": 600, // maximum allowed number of characters
                // all display_* parameters can be used to generate UI elements in your frontend application
                "display_help": "<p>e.g. 'A fine oil painting of ducks flying by Pablo Picasso and Wasilly Kandansky, trending on twitter'</p><p>or</p><p>'Realistic concept art of a pathway through a dark forest, abstract, popart featured on Facebook Marketplace'</p><p>&nbsp;</p><p>Learn more about Prompt Craft <a href='/static/imaginarium/help/prompt-craft.pdf' target='_blank'>here</a>.</p>",
                "display_wide": true,
                "display_label": "Describe the image you wish to create and list any stylistic influences",
                "display_element": "textarea",
                "parsePrompt": true, // system parameter
                "imagine_text": true // system parameter

            },
            "negative_text": { // to be used as `negative_text` parameter in the 'Generate imagine' endpoint
                "name": "Negative Text Prompt",
                "type": "textarea",
                "max_value": 400, // maximum allowed number of characters
                "default_value": "", // parameter default value
                "display_help": "<p>e.g. 'watermark', 'extra arms' or 'stinky cats'</p>",
                "display_wide": true,
                "display_label": "Describe things to avoid when imagining.",
                "display_element": "textarea"
            },
            "seed": { // to be used as `seed` parameter in the 'Generate imagine' endpoint
                "name": "Generation Seed",
                "type": "int",
                "max_value": 2147483647, // maximum accepted value of the seed number
                "min_value": -1, // minimum accpted value of the seed number
                "default_value": 0, // parameter default value
                "display_help": "<p>Choose 0 for a random seed. Any other number set will be used to \"freeze\" the image generator generator and create similar images using the same seed number and settings.</p>",
                "display_label": "Image Generation Seed",
                "display_element": "input",
                "parse_random": true, // system parameter
                "random_max_value": 2147483647, // system parameter
                "random_min_value": 1 // system parameter
            },
            "animation_mode": { // to be used as `animation_mode` parameter in the 'Generate imagine' endpoint
                "name": "Animation Mode",
                "type": "select",
                "options": [
                    {
                        "label": "Skybox",
                        "value": "skybox"
                    }
                ],
                "required": false,
                "default_value": "skybox",
                "display_label": "Generation Mode",
                "display_element": "select"
            }
        },
        "sort_order": 1
    }
]

# Generate Imagine

# Method

POST

# API Endpoint

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

# Params

Key Data Type Description
api_key String Your API Key required
generator String generator parameter you get from the /api/v1/generators request. ie. "stable-skybox" required
*generator parameters Any parameter defined in the generator (prompt, negative_text, seed, etc.)
webhook_url String Optionally, you may specify a webhook url to specify the destination for progress updates optional

# Example Request With Generator Params

Key Data Type Value example
api_key String 7J7eD5TIiJR4GkytWvsPZNlw5BdDFtj2qlwM1sVQHBnzY1sdhRndiVMOCZx required
generator String stable-skybox required
prompt String forest in autumn, detailed digital painting,cinematic lighting required
negative_text String blurry, lowres, text, error, worst quality, low quality, bad quality optional
seed Int 1432443 optional
animation_mode String skybox optional
webhook_url String https://example.com/webhook_endpoint optional

TIP

Available parameters for generators can retrieved by making GET request to /api/v1/generators. Explained in more detail here.

# Response

{
  "response" : {
    "id": 123456, // id of your generation. It can be used to track generation progress or to cancel 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
    "type": "imaginarium", // type of generation
    "generator": "stable-skybox", // generator type
    "generator_data": { // generator parameters used
      "prompt": "forest in autumn, detailed digital painting,cinematic lighting",
      "negative_text": "blurry, lowres, text, error, worst quality, low quality, bad quality",
      "seed": 1432443,
      "animation_mode": "skybox"
    }
  }
}

TIP

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

# Errors

Code Message
400 Various invalid generator data related errors
403 Account does not have access to this method

# Get Imagine by id

# Method

GET

# API Endpoint

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

# Params

Key Data Type Description
api_key String Your API Key required

# Response

{
  "response" : {
    "id": 123456, // id of your generation. It can be used to track generation progress or to cancel the generation
    "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
    "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",
    "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: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
    "type": "imaginarium", // type of generation
    "generator": "stable-skybox", // generator type
    "generator_data": { // the generator parameters used
      "prompt": "forest in autumn, detailed digital painting,cinematic lighting",
      "negative_text": "blurry, lowres, text, error, worst quality, low quality, bad quality",
      "seed": 1432443,
      "animation_mode": "skybox"
    }
  }
}

# Get Imagine by Obfuscated id

# Method

GET

# API Endpoint

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

# Params

Key Data Type Description
api_key String Your API Key required

# Response

{
  "response" : {
    "id": 123456, // id of your generation. It can be used to track generation progress or to cancel the generation
    "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
    "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",
    "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: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
    "type": "imaginarium", // type of generation
    "generator": "stable-skybox", // generator type
    "generator_data": { // the generator parameters used
      "prompt": "forest in autumn, detailed digital painting,cinematic lighting",
      "negative_text": "blurry, lowres, text, error, worst quality, low quality, bad quality",
      "seed": 1432443,
      "animation_mode": "skybox"
    }
  }
}

# Get Imagine History

# Method

GET

# API Endpoint

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

# Params

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

# Response

{
  "data": [
    {
      "id": 123456, // id of your generation. It can be used to track generation progress or to cancel the generation
      "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
      "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",
      "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: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
      "type": "imaginarium", // type of generation
      "generator": "stable-skybox", // generator type
      "generator_data": { // the generator parameters used
        "prompt": "forest in autumn, detailed digital painting,cinematic lighting",
        "negative_text": "blurry, lowres, text, error, worst quality, low quality, bad quality",
        "seed": 1432443,
        "animation_mode": "skybox"
      }
    }
  ],
  "totalCount": 1,
  "has_more": false
}

# Cancel Imagine

# Method

DELETE

# API Endpoint

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

TIP

This request sets the status of the Imagine Request to the abort value.

# Params

Key Data Type Description
api_key String Your API Key required

# Response

{
  "success": true
}

# Cancel All Pending Imagines

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

# Method

DELETE

# API Endpoint

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

# Params

Key Data Type Description
api_key String Your API Key required

# Response

{
  "success": true
}

# Delete Imagine

This request deletes imagine.

# Method

DELETE

# API Endpoint

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

# Params

Key Data Type Description
api_key String Your API Key required

# Response

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