Getting Started

Note

Access to the API is currently in preview mode.

• Accounts are only activated for selected partners.
• The API is not stable and subject to change.

Our API endpoints enable media creation with generative models. It follows an asynchronous design, where you first make a request for a generation and then query for the result of your request. On this page, we provide an example to create an image from a text prompt.

Obtain an API key

To get started, create an account at api.bfl.ml. After confirming your E-Mail, sign in and add a new API key. To follow along, store your API key in an environment variable BFL_API_KEY:

export BFL_API_KEY="<your key>"

Create an image

Create request

To generate an image from a prompt, create a request:

bashpython

Install curl and run

request=$(curl -X 'POST' \
  'https://api.bfl.ml/v1/image' \
  -H 'accept: application/json' \
  -H "x-key: ${BFL_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "prompt": "A cat on its back legs running like a human is holding a big silver fish with its arms. The cat is running away from the shop owner and has a panicked look on his face. The scene is situated in a crowded market.",
  "width": 1024,
  "height": 1024
}')
echo $request
request_id=$(jq -r .id <<< $request)

Install requests (e.g. pip install requests) and run

import os
import requests

request = requests.post(
    'https://api.bfl.ml/v1/image',
    headers={
        'accept': 'application/json',
        'x-key': os.environ.get("BFL_API_KEY"),
        'Content-Type': 'application/json',
    },
    json={
        'prompt': 'A cat on its back legs running like a human is holding a big silver fish with its arms. The cat is running away from the shop owner and has a panicked look on his face. The scene is situated in a crowded market.',
        'width': 1024,
        'height': 1024,
    },
).json()
print(request)
request_id = request["id"]

A successful response will be a json object containing the request's id, that will be used to retrieve the actual result.

Poll for result

To retrieve the result, you can poll the get_result endpoint:

bashpython

This assumes that the request id is stored in a request_id variable as it was done in the previous step.

while true
do
  sleep 0.5
  result=$(curl -s -X 'GET' \
    "https://api.bfl.ml/v1/get_result?id=${request_id}" \
    -H 'accept: application/json' \
    -H "x-key: ${BFL_API_KEY}")
  if [ "$( jq -r .status <<< $result )" == "Ready" ]
  then
    echo "Result: $(jq -r .result.sample <<< $result)"
    break
  else
    echo "Status: $(jq -r .status <<< $result)"
  fi
done

This assumes that the request id is stored in a request_id variable and that the os and requests packages were imported as it was done in the previous step.

import time

while True:
    time.sleep(0.5)
    result = requests.get(
        'https://api.bfl.ml/v1/get_result',
        headers={
            'accept': 'application/json',
            'x-key': os.environ.get("BFL_API_KEY"),
        },
        params={
            'id': request_id,
        },
    ).json()
    if result["status"] == "Ready":
        print(f"Result: {result['result']['sample']}")
        break
    else:
        print(f"Status: {result['status']}")

See our reference documentation for a full list of options.

Limits

Please note that sending requests to /v1/image is limited to 12 active tasks. If you exceed your limit, it will return a status code 429 and you will have to wait until one of your previous tasks has finished. If you require higher volumes, please contact us at flux@blackforestlabs.ai

If you run out of credits (status code 402) you can go to https://api.bfl.ml, sign in and click "Add" to buy additional credits. See also our pricing.