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

# Generate Image

> Generate images from text prompts.

# Generate Image <Badge color="green" shape="pill">Live</Badge>

```text theme={null}
POST /v1/images/generations
```

Generate an image from a text prompt. The endpoint can return synchronously or queue work for async delivery when a `callback_url` is supplied.

## Request body

| Parameter             | Type    | Required | Description                                                                                                                                                                          |
| --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt`              | string  | Yes      | Text prompt describing the image. 1-2,000 characters after trimming; cannot be empty.                                                                                                |
| `model`               | string  | Yes      | Image model to use. The API defaults to `model-dev` if omitted, but integrations should send this explicitly. See [Image Models](/images/models).                                    |
| `image_width`         | integer | No       | Width in pixels. Schema accepts 256-2,048. Some providers clamp or map dimensions internally. Default: `1024`.                                                                       |
| `image_height`        | integer | No       | Height in pixels. Schema accepts 256-2,048. Some providers clamp or map dimensions internally. Default: `1024`.                                                                      |
| `callback_url`        | string  | No       | Webhook URL for async delivery.                                                                                                                                                      |
| `resolution`          | string  | No       | Top-level convenience param for variable-size models. Also passed to provider settings.                                                                                              |
| `quality`             | string  | No       | Top-level convenience param for quality-priced models. Also passed to provider settings.                                                                                             |
| `additional_settings` | object  | No       | Model-specific settings such as `seed`, `aspect_ratio`, `negative_prompt`, `num_inference_steps`, `guidance_scale`, `output_format`, `enable_web_search`, and `enable_image_search`. |
| `enable_fallback`     | boolean | No       | Defaults to `true`. Image generation models currently have no fallback configured.                                                                                                   |

## Model support

See [Image Models](/images/models) for every live model's required params, optional supported params, cost, and ETA.

## Example request

```bash theme={null}
curl --request POST "https://api.uncensored.com/api/v1/images/generations" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "A beautiful sunset over mountains, photorealistic, 8k",
    "model": "model-pro",
    "image_width": 1024,
    "image_height": 1024
  }'
```

## Sync response

```json theme={null}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "url": "https://media.lesscensored.com/images/550e8400.jpg",
  "generation_time": 2.5,
  "model": "model-pro"
}
```

## Async request

```json theme={null}
{
  "prompt": "A cyberpunk cityscape at night",
  "model": "model-pro",
  "image_width": 1024,
  "image_height": 1024,
  "callback_url": "https://your-server.com/webhook"
}
```

## Async response

```json theme={null}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "status_url": "https://api.uncensored.com/api/v1/images/generation/jobs/550e8400-e29b-41d4-a716-446655440000",
  "webhook_url": "https://your-server.com/webhook",
  "created_at": "2026-05-09T10:30:00Z"
}
```

## Get image job status

```text theme={null}
GET /v1/images/generation/jobs/{job_id}
```

Poll every 2-5 seconds. Image generation typically takes 5-30 seconds.

```json theme={null}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "image_url": "https://media.lesscensored.com/images/550e8400.jpg",
  "model": "model-pro",
  "created_at": "2026-05-09T10:30:00Z",
  "completed_at": "2026-05-09T10:30:05Z",
  "generation_time": 2.5
}
```

## Status codes

| Status code | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `200`       | Image generated successfully in sync mode.                      |
| `202`       | Job accepted and queued for async mode.                         |
| `400`       | Invalid request parameters.                                     |
| `402`       | Insufficient funds.                                             |
| `403`       | Content moderation failed, or scope does not permit this model. |
| `429`       | Rate limit exceeded.                                            |
| `500`       | Internal server error.                                          |