Skip to main content

​
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

ParameterTypeRequiredDefaultDescription
modelstringyes—Image model name (e.g. black-forest-labs-flux-2-klein-4b, flux-2-dev)
promptstringyes—Text description of the image to generate.
response_formatstringno"url""url" returns a hosted URL. "b64_json" returns base64-encoded image bytes inline.
target_namespacestringnocurrent userNamespace to save results and bill to. Can be an organization name.
aspect_ratiostringno—Aspect ratio (e.g. "1:1", "16:9", "9:16", "4:3", "3:4").
num_inference_stepsintegerno—Number of denoising steps.
seedintegerno—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"])

​
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

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