Image Generation

Generate images from text prompts in minutes

Overview

Generate images from text descriptions using models like FLUX and DALL-E.

Minimal Example (Synchronous)

Python

import requests

response = requests.post(
    "https://hub.oxen.ai/api/ai/images/generate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "black-forest-labs-flux-2-klein-4b",
        "prompt": "A red cube on a white background, minimal",
    },
)

data = response.json()
print("Image URL:", data["images"][0]["url"])

curl -X POST https://hub.oxen.ai/api/ai/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs-flux-2-klein-4b",
    "prompt": "A red cube on a white background, minimal"
  }'

With Base64 Response

Set response_format to "b64_json" to get the image bytes directly instead of a URL:

Python

import requests
import base64

response = requests.post(
    "https://hub.oxen.ai/api/ai/images/generate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "black-forest-labs-flux-2-klein-4b",
        "prompt": "A blue sphere on grey background",
        "response_format": "b64_json",
    },
)

data = response.json()
image_bytes = base64.b64decode(data["images"][0]["b64_json"])

with open("output.png", "wb") as f:
    f.write(image_bytes)

print("Saved to output.png")

curl -X POST https://hub.oxen.ai/api/ai/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs-flux-2-klein-4b",
    "prompt": "A blue sphere on grey background",
    "response_format": "b64_json"
  }'

Async Generation (Recommended)

For longer-running image generation jobs, using the async queue avoids long-lived HTTP connections:

Python

import requests
import time

API_KEY = "YOUR_API_KEY"
MODEL = "black-forest-labs-flux-2-klein-4b"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. Enqueue
response = requests.post(
    "https://hub.oxen.ai/api/ai/queue",
    headers=HEADERS,
    json={
        "model": MODEL,
        "prompt": "A watercolor painting of a mountain landscape",
    },
)
generation_id = response.json()["generations"][0]["generation_id"]
print(f"Enqueued generation: {generation_id}")

# 2. Poll until done
while True:
    data = requests.get(
        f"https://hub.oxen.ai/api/ai/queue/{generation_id}",
        headers=HEADERS,
    ).json()
    print(f"Status: {data['status']}")
    if data["status"] in {"succeeded", "failed", "cancelled"}:
        break
    time.sleep(10)

if data["status"] == "succeeded":
    print(f"Done! Result: {data['result_url']}")
else:
    print(f"Generation {data['status']}: {data.get('error_message')}")

# 1. Enqueue
curl -X POST https://hub.oxen.ai/api/ai/queue \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs-flux-2-klein-4b",
    "prompt": "A watercolor painting of a mountain landscape"
  }'

# 2. Poll until done (replace GENERATION_ID with the id from the enqueue response)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://hub.oxen.ai/api/ai/queue/GENERATION_ID"

What’s Next

• Image Generation Reference for the full parameter list
• Image Editing Reference to edit existing images
• Async Queue to generate multiple images in parallel