notrius/runpod-fluxdev-serverless repository overview

⁠FLUX.1-dev Serverless Worker

Serverless FLUX.1-dev text-to-image generation with Redis caching, minus the goldfish-memory cold start.

This repo turns FLUX.1-dev into a RunPod serverless template that keeps its brain on /workspace: Python venv, caches, and downloaded model assets survive worker churn instead of being painfully rediscovered on every boot.

Less boot drama. More actual inference.

⁠Quickstart

The simplest way to get started is to pull a pre-built Docker image from Docker Hub and deploy it as a RunPod serverless endpoint.

Pre-built images include both the FLUX.1-dev handler and the model in diffusers format.

1. Pull a pre-built Docker image from Docker Hub.
2. Create a RunPod serverless template that uses that image.
3. Attach a network volume so /workspace is persistent (optional but recommended).
4. Deploy the endpoint with Active Workers = 0 unless you enjoy paying for idle GPUs.
5. Send requests to the endpoint with a text prompt.

Hardware requirements: 12GB+ VRAM and 16GB+ free disk recommended. See Deployment Guide⁠ for details.

⁠API Specification

⁠Input Format

{
  "input": {
    "prompt": "A futuristic city at sunset, cinematic lighting",
    "width": 1024,
    "height": 1024,
    "num_inference_steps": 50,
    "guidance_scale": 3.5,
    "seed": 42
  }
}

⁠Output Format

{
  "status": "success",
  "image": "base64_encoded_png_data",
  "metadata": {
    "generation_time_sec": 12.5,
    "seed": 42
  },
  "cached": false
}

⁠Essential Configuration

The FLUX.1-dev model is included in the Docker image, so no preload is needed. Workspace persistence caches Python venv and other assets across worker restarts.

For the full list of environment variables, see Configuration Guide⁠.

⁠Testing the Endpoint

⁠Local Testing

You can test the endpoint locally using docker-compose:

docker-compose up --build
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "A futuristic city at sunset, cinematic lighting",
      "width": 1024,
      "height": 1024,
      "num_inference_steps": 50,
      "guidance_scale": 3.5,
      "seed": 42
    }
  }'

⁠Sample API Response

{
  "status": "success",
  "image": "iVBORw0KGgoAAAANSUhEUgAA...<truncated base64 PNG data>...A5ElFTkSuQmCC",
  "metadata": {
    "generation_time_sec": 12.5,
    "seed": 42
  },
  "cached": false
}

The image field contains a base64-encoded PNG image. Decode it to view or save the generated image:

echo "iVBORw0KGgoAAAANSUhEUgAA..." | base64 -d > output.png

⁠Documentation

• Deployment Guide⁠ - Detailed RunPod template/endpoint creation, GPU recommendations
• Configuration Guide⁠ - Comprehensive list and explanation of all environment variables
• Customization Guide⁠ - In-depth guide on using Network Volumes and building custom Docker images
• Network Volumes & Model Paths⁠ - How to use network volumes and debug model detection issues
• Development Guide⁠ - Instructions for local setup, running tests, using docker-compose
• CI/CD Guide⁠ - Explanation of the GitHub Actions workflows for Docker Hub deployment
• Conventions⁠ - Project conventions and rules for development
• Acknowledgments⁠ - Credits and thanks