Image Generation

Generate images from text prompts

Endpoint

POST /api/ai/images/generate

Generates images synchronously. The request blocks until the image is ready (typically 5-30 seconds depending on the model).

Request Parameters

Parameter	Type	Required	Default	Description
model	string	yes	—	Image model name (e.g. black-forest-labs-flux-2-klein-4b, flux-2-dev)
prompt	string	yes	—	Text description of the image to generate.
response_format	string	no	"url"	"url" returns a hosted URL. "b64_json" returns base64-encoded image bytes inline.
target_namespace	string	no	current user	Namespace to save results and bill to. Can be an organization name.
aspect_ratio	string	no	—	Aspect ratio (e.g. "1:1", "16:9", "9:16", "4:3", "3:4").
num_inference_steps	integer	no	—	Number of denoising steps.
seed	integer	no	—	Reproducibility seed.

Available parameters vary by model. Use the model detail endpoint (GET /api/ai/models/:id) to see the request_schema for model-specific parameters.

Examples

Basic generation

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",
        "aspect_ratio": "1:1",
        "seed": 42,
    },
)

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

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

Response (response_format: "url")

{
  "model": "black-forest-labs-flux-2-klein-4b",
  "created": 1775090372,
  "images": [
    {
      "url": "https://hub.oxen.ai/api/repos/.../files/.../image.png?..."
    }
  ]
}

The URL is a temporary link that expires after a period of time.

Response (response_format: "b64_json")

{
  "model": "black-forest-labs-flux-2-klein-4b",
  "created": 1775090372,
  "images": [
    {
      "b64_json": "<base64-encoded image bytes>"
    }
  ]
}

Errors

Condition	Error
No prompt	"Prompt cannot be empty"
Model not found	"Model not found: <name>"