API documentation

Introduction

The Fusion Brain API is a new section of the platform that allows platform users to access artificial intelligence models via the API. One of the first models that is available via the API is the Kandinsky model.

Kandinsky is an artificial intelligence model that can create realistic images and works of art based on natural language descriptions.

Currently, via the API is available the Kandinsky 3.0 with more realistic, accurate images.

API Usage Features and Limitations

Let's take a closer look at the technical characteristics of the model and examples of requests for each of the parameters. And if you want to take action as soon as possible - move below.

Model Modes

Currently, Kandinsky is available via the API in one mode for working with images:

• generation mode generate: creating images based on a text description

This parameter is specified as:

"type": "GENERATE",

Image Sizes

The generated images can have a size of up to 1024 pixels on each side.

Also in version 3.0, image generation with different aspect ratios is supported (the most optimal aspect ratio - 1:1 / 2:3 / 3:2 / 9:16 / 16:9).

These parameters are specified as mention below (you need to choose the ratio yourself):

"width": 1024,
"height": 1024,

Number of images

You can only request 1 image at a time for the same request.

"numImages": 1,

Request

You and your users can make requests in Russian, English or any other language. It is also allowed to use emoji in the text description.

The maximum size of a text description is 1000 characters.

Request example:

"query": "Fluffy cat with glasses",

Style

You and your users can also use several styles from our presets for generation.

"style": "ANIME",

Getting the current list of styles is carried out by URL: cdn.fusionbrain.ai/static/styles/key.

Negative prompt

In the Negative prompt field, you can specify which colors and techniques the model should not use when generating an image.

"negativePromptUnclip": "bright colors, acidity, high contrast",

Example of request transmission:

{
  "type": "GENERATE",
  "style": "string",
  "width": 1024,
  "height": 1024,
  "num_images": 1,
  "negativePromptUnclip": "bright colors, acidity, high contrast",
  "generateParams": {
    "query": "Fluffy cat with glasses",
  }
}

Generation results

Regardless of the selected mode, the result of the model is an image. Each image can be returned as Base64 data using the images parameter.

"images": ["string"]

Content moderation

Generation requests and images pass the appropriate censorship filters in accordance with our content policy, returning an error when the request or image does not match.

Example of working out this parameter:

"censored": true

Description of requests

Authentication of the API key

The first step after receiving the key is to authenticate it.

The API key and Secret must be transmitted at any request to the service.

HTTP request headers are used for transmission: X-Key and X-Secret, prefixes Key, Secret, respectively. We will prepare all the necessary values:

def __init__(self, url, api_key, secret_key):
    self.URL = url
    self.AUTH_HEADERS = {
        'X-Key': f'Key {api_key}',
        'X-Secret': f'Secret {secret_key}',
    }

Next, you will need to refer to the list of available models and select Kandinsky 3.0 (currently this is the only model available for API connection). The appeal takes place at the URL: https://api-key.fusionbrain.ai/.

To do this, make the following request:

def get_model(self):
    response = requests.get(self.URL + 'key/api/v1/models', headers=self.AUTH_HEADERS)
    data = response.json()
    return data[0]['id']

Response structure:

[
	{
		"id": 1,
		"name": "string",
		"version": 1.0,
		"type": "TEXT2IMAGE"
	}
]

Recall that the Kandinsky API supports one mode of operation of the model: GENERATE. Request to the model (using the generate mode)

The generate mode takes a text description of an image as input and generates an image corresponding to it. To call this method, you need to send a POST request to the URL /key/api/v1/text2image/run.

The request must contain the following parameters:

• query: text description of the image
• height width: output image dimensions
• num_images: the number of images for this request

Request example:

def generate(self, prompt, model, images=1, width=1024, height=1024):
	params = {
		"type": "GENERATE",
		"numImages": images,
		"width": width,
		"height": height,
		"generateParams": {
			"query": f"{prompt}"
		}
	}

  data = {
		'model_id': (None, model),
		'params': (None, json.dumps(params), 'application/json')
	}
	response = requests.post(self.URL + 'key/api/v1/text2image/run', headers=self.AUTH_HEADERS, files=data)
	data = response.json()
	return data['uuid']

Response structure:

{
	"uuid": "string",
	"status": "INITIAL"
}

Service availability

If there is a heavy load or technical work, the service may be temporarily unavailable to accept new tasks. You can check the current status in advance by using a GET request to URL /key/api/v1/text2image/availability. During unavailability, tasks will not be accepted and in response to a request to the model, instead of the uuid of your task, the current status of the service will be returned.

Example:

{
  "model_status": "DISABLED_BY_QUEUE"
}

Requests to check the status

The check_status request allows you to check the status of image generation. To call this method, you need to send a GET request to the URL запрос на URL /key/api/v1/text2image/status/{uuid}, where uid is the task ID received when calling the request to the model.

Request example:

def check_generation(self, request_id, attempts=10, delay=10):
	while attempts > 0:
		response = requests.get(self.URL + 'key/api/v1/text2image/status/' + request_id, headers=self.AUTH_HEADERS)
		data = response.json()
		if data['status'] == 'DONE':
			return data['images']

		attempts -= 1
		time.sleep(delay)

The response contains the current status of the task:

{
  "uuid": "string",
  "status": "string",
  "images": ["string"],
  "errorDescription": "string",
  "censored": "false"
}

It is important to note that the image is received only once, it cannot be requested again.

Possible values of the status field:

• INITIAL- the request has been received, is in the queue for processing
• PROCESSING - the request is being processed
• DONE- task completed
• FAIL- the task could not be completed.

Error Handling

The API may return the following errors:

• 401 Unauthorized - authorization error
• 404 Not found - resource not found
• 400 Bad Request - invalid request parameters or the text description is too long
• 500 Internal Server Error - server error when executing the request
• 415 Unsupported Media Type - the content format is not supported by the server

If error 415 occurs, we recommend using this script, which must be sent to postman.

curl --location --request POST 'https://api-key.fusionbrain.ai/key/api/v1/text2image/run' \
--header 'X-Key: Key YOUR_KEY' \
--header 'X-Secret: Secret YOUR_SECRET' \
-F 'params="{
  \"type\": \"GENERATE\",
  \"generateParams\": {
    \"query\": \"море\"
  }
}";type=application/json' \
--form 'model_id="1"'

#Don't forget to specify exactly YOUR_KEY and YOUR_SECRET.

Usage examples

Python

Example of using the API in Python:

import json
import time

import requests


class Text2ImageAPI:

    def __init__(self, url, api_key, secret_key):
        self.URL = url
        self.AUTH_HEADERS = {
            'X-Key': f'Key {api_key}',
            'X-Secret': f'Secret {secret_key}',
        }

    def get_model(self):
        response = requests.get(self.URL + 'key/api/v1/models', headers=self.AUTH_HEADERS)
        data = response.json()
        return data[0]['id']

    def generate(self, prompt, model, images=1, width=1024, height=1024):
        params = {
            "type": "GENERATE",
            "numImages": images,
            "width": width,
            "height": height,
            "generateParams": {
                "query": f"{prompt}"
            }
        }

        data = {
            'model_id': (None, model),
            'params': (None, json.dumps(params), 'application/json')
        }
        response = requests.post(self.URL + 'key/api/v1/text2image/run', headers=self.AUTH_HEADERS, files=data)
        data = response.json()
        return data['uuid']

    def check_generation(self, request_id, attempts=10, delay=10):
        while attempts > 0:
            response = requests.get(self.URL + 'key/api/v1/text2image/status/' + request_id, headers=self.AUTH_HEADERS)
            data = response.json()
            if data['status'] == 'DONE':
                return data['images']

            attempts -= 1
            time.sleep(delay)


if __name__ == '__main__':
    api = Text2ImageAPI('https://api-key.fusionbrain.ai/', 'YOUR_API_KEY', 'YOUR_SECRET_KEY')
    model_id = api.get_model()
    uuid = api.generate("Sun in sky", model_id)
    images = api.check_generation(uuid)
    print(images)

#Don't forget to specify exactly YOUR_KEY and YOUR_SECRET.

Conclusion

The Kandinsky API for creating unique images provides a convenient way to generate realistic content for your products and services. Following the instructions in this documentation, you can easily integrate the API into your project. If you have any questions or suggestions, please contact us at hello@fusionbrain.ai.