> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oxen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/inference-api/reference/models/overview#retrieve-model) (`GET /api/ai/models/:id`) to see the `request_schema` for model-specific parameters.

## Examples

### Basic generation

<CodeGroup>
  ```python Python theme={null}
  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"])
  ```

  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

### Response (`response_format: "url"`)

```json theme={null}
{
  "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"`)

```json theme={null}
{
  "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>"` |