FLUX.1-dev API

A Docker-based API for generating images with the FLUX.1-dev model from Black Forest Labs.

Features

• Simple REST API: Generate images by sending HTTP requests
• Docker-based: Easy deployment with Docker and Docker Compose
• GPU Accelerated: Utilizes CUDA for fast image generation
• Persistent Storage: Model files are downloaded once and reused
• Customizable: Configure image size, steps, and other parameters

Requirements

• Docker and Docker Compose
• NVIDIA GPU with CUDA 12.8 drivers
• NVIDIA Container Toolkit installed
• Hugging Face account with access to FLUX.1-dev model
• At least 20GB of free disk space for the model

Quick Start

1. Clone this repository:

   git clone https://github.com/yourusername/flux-api.git
   cd flux-api

2. Create environment file:

   cp .env.example .env

   Edit .env and add your Hugging Face token:

   HUGGINGFACE_TOKEN=your_huggingface_token_here
   

   You can create a token at https://huggingface.co/settings/tokens

3. Create directories for persistent storage:

   mkdir -p models outputs

4. Build and start the container:

   docker compose up --build

   The API will be available at http://localhost:2030

WSL2 Integration with Docker Desktop

If you're using WSL2 and Docker Desktop, make sure:

1. WSL integration is enabled in Docker Desktop (Settings > Resources > WSL Integration)
2. NVIDIA Container Toolkit is properly configured

API Endpoints

Generate an Image

POST /generate

Request body:

{
    "prompt": "A stunning mountain landscape at sunset",
    "negative_prompt": "blurry, low quality",
    "width": 1024,
    "height": 1024,
    "num_inference_steps": 50,
    "guidance_scale": 3.5,
    "max_sequence_length": 512,
    "seed": 12345
}

Parameters:

• prompt (required): Text description of the image to generate
• negative_prompt (optional): Text describing what to avoid in the image
• width (optional, default: 1024): Width of the generated image
• height (optional, default: 1024): Height of the generated image
• num_inference_steps (optional, default: 50): Number of denoising steps
• guidance_scale (optional, default: 3.5): How closely to follow the prompt
• max_sequence_length (optional, default: 512): Maximum token length for prompt processing
• seed (optional): Random seed for reproducible results

Response:

{
    "status": "success",
    "filename": "flux-20240408-123456-abcd1234.png",
    "filepath": "/app/outputs/flux-20240408-123456-abcd1234.png",
    "download_url": "/download/flux-20240408-123456-abcd1234.png"
}

Download an Image

GET /download/{filename}

Returns the generated image as a PNG file.

Get API Status

GET /status

Returns information about the API, model loading status, and CUDA availability.

Example Usage

Python

import requests

# Generate an image
response = requests.post(
    "http://localhost:2030/generate",
    json={
        "prompt": "A beautiful sunset over mountains",
        "negative_prompt": "blurry, low quality",
        "num_inference_steps": 50,
        "guidance_scale": 3.5,
        "width": 1024,
        "height": 1024
    }
)

# Get the download URL from the response
result = response.json()
print(f"Image generated: {result['filename']}")

# Download the image
image_response = requests.get(f"http://localhost:2030{result['download_url']}")
with open(f"generated_{result['filename']}", "wb") as f:
    f.write(image_response.content)

cURL

# Generate an image
curl -X POST http://localhost:2030/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A beautiful sunset over mountains", "negative_prompt": "blurry, low quality", "num_inference_steps": 50, "guidance_scale": 3.5}'

# Download the image (replace with the filename from the response)
curl -o generated_image.png http://localhost:2030/download/flux-20240408-123456-abcd1234.png

Notes

• The model is downloaded on first startup (20+ GB), which may take some time
• Generated images are saved in the outputs directory and persist between container restarts
• The model is stored in the models directory and persists between container restarts

License

This project uses the FLUX.1-dev model, which is licensed under the FLUX.1-dev Non-Commercial License.