Image Generation - Oxen.ai

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

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>"`