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

# Image Generation

> Generate images with DALL-E, Stable Diffusion, Flux, and more

# Image Generation API

Generate images using state-of-the-art models including DALL-E 3, Stable Diffusion 3, Flux, and Ideogram. The API follows the OpenAI Images API format for easy integration.

## Endpoint

```
POST https://api.withperf.pro/v1/images/generations
```

## Authentication

Include your API key in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

### Required Parameters

| Parameter | Type   | Description                                              |
| --------- | ------ | -------------------------------------------------------- |
| `prompt`  | string | A text description of the desired image (max 4000 chars) |

### Optional Parameters

| Parameter         | Type   | Default     | Description                                                    |
| ----------------- | ------ | ----------- | -------------------------------------------------------------- |
| `model`           | string | `dall-e-3`  | Model to use for generation                                    |
| `n`               | number | `1`         | Number of images to generate (1 for DALL-E 3, 1-10 for others) |
| `size`            | string | `1024x1024` | Image dimensions                                               |
| `quality`         | string | `standard`  | Quality level (`standard` or `hd`, DALL-E 3 only)              |
| `style`           | string | `vivid`     | Style preset (`vivid` or `natural`, DALL-E 3 only)             |
| `response_format` | string | `url`       | Return format (`url` or `b64_json`)                            |

## Supported Models

| Model                | Provider          | Sizes                           | Max Images | Pricing                                    |
| -------------------- | ----------------- | ------------------------------- | ---------- | ------------------------------------------ |
| `dall-e-3`           | OpenAI            | 1024x1024, 1792x1024, 1024x1792 | 1          | $0.040/image (standard), $0.080/image (HD) |
| `dall-e-2`           | OpenAI            | 256x256, 512x512, 1024x1024     | 10         | \$0.016-0.020/image                        |
| `stable-diffusion-3` | Stability AI      | 1024x1024, custom               | 4          | \$0.035/image                              |
| `flux-pro`           | Black Forest Labs | 1024x1024, custom               | 4          | \$0.055/image                              |
| `flux-dev`           | Black Forest Labs | 1024x1024, custom               | 4          | \$0.025/image                              |
| `ideogram-2`         | Ideogram          | 1024x1024, custom               | 4          | \$0.040/image                              |
| `imagen-3`           | Google            | 1024x1024                       | 4          | \$0.040/image                              |

## Request Examples

### cURL

```bash theme={null}
curl -X POST https://api.withperf.pro/v1/images/generations \
  -H "Authorization: Bearer pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene Japanese garden with cherry blossoms at sunset, photorealistic",
    "model": "dall-e-3",
    "size": "1024x1024",
    "quality": "hd",
    "style": "vivid"
  }'
```

### JavaScript

```javascript theme={null}
const response = await fetch('https://api.withperf.pro/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_live_abc123',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A serene Japanese garden with cherry blossoms at sunset, photorealistic',
    model: 'dall-e-3',
    size: '1024x1024',
    quality: 'hd'
  })
});

const data = await response.json();
console.log(data.data[0].url);
```

### Python

```python theme={null}
import requests

response = requests.post(
    'https://api.withperf.pro/v1/images/generations',
    headers={
        'Authorization': 'Bearer pk_live_abc123',
        'Content-Type': 'application/json'
    },
    json={
        'prompt': 'A serene Japanese garden with cherry blossoms at sunset, photorealistic',
        'model': 'dall-e-3',
        'size': '1024x1024',
        'quality': 'hd'
    }
)

data = response.json()
print(data['data'][0]['url'])
```

## Response

### Success Response (200 OK)

```json theme={null}
{
  "created": 1706123456,
  "data": [
    {
      "url": "https://storage.withperf.pro/images/abc123.png",
      "revised_prompt": "A serene traditional Japanese garden featuring pink cherry blossom trees in full bloom, with petals gently falling over a stone path and koi pond, bathed in warm golden sunset light, photorealistic style"
    }
  ],
  "perf": {
    "request_id": "req_img_abc123",
    "model_used": "dall-e-3",
    "size": "1024x1024",
    "quality": "hd",
    "cost_usd": 0.080,
    "latency_ms": 5234
  }
}
```

### Response Fields

| Field                   | Type   | Description                                             |
| ----------------------- | ------ | ------------------------------------------------------- |
| `created`               | number | Unix timestamp of generation                            |
| `data`                  | array  | Array of generated images                               |
| `data[].url`            | string | URL to the generated image (expires after 1 hour)       |
| `data[].b64_json`       | string | Base64-encoded image (if `response_format: "b64_json"`) |
| `data[].revised_prompt` | string | The actual prompt used (DALL-E 3 rewrites prompts)      |
| `perf.request_id`       | string | Unique request identifier for tracking                  |
| `perf.model_used`       | string | Model that generated the image                          |
| `perf.size`             | string | Image dimensions                                        |
| `perf.quality`          | string | Quality level used                                      |
| `perf.cost_usd`         | number | Cost of this generation                                 |
| `perf.latency_ms`       | number | Generation time in milliseconds                         |

## Prompt Best Practices

### Be Specific

```json theme={null}
{
  "prompt": "A red 1965 Ford Mustang convertible parked in front of a neon-lit diner at night, rain-wet street reflecting the lights, cinematic photography style"
}
```

### Specify Style

```json theme={null}
{
  "prompt": "Portrait of a wise elderly wizard with a long white beard, oil painting style, dramatic lighting, renaissance art influence"
}
```

### Use Negative Guidance

For models that support it, describe what you don't want:

```json theme={null}
{
  "prompt": "A clean modern kitchen interior, minimalist design, no people, no text, professional architectural photography"
}
```

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "message": "prompt is required",
    "param": "prompt"
  }
}
```

### 400 Content Policy Violation

```json theme={null}
{
  "error": {
    "type": "content_policy_violation",
    "message": "Your request was rejected as a result of our safety system."
  }
}
```

### 429 Rate Limit

```json theme={null}
{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded for image generation",
    "retry_after": 60
  }
}
```

## Rate Limits

| Tier       | Images/Minute | Images/Day |
| ---------- | ------------- | ---------- |
| Free       | 5             | 50         |
| Pro        | 30            | 1,000      |
| Enterprise | Custom        | Custom     |

## Related Endpoints

* [Chat API (with Vision)](./chat) - Send images to models for analysis
* [Video Generation](./video) - Generate video content
* [Audio Generation](./audio) - Text-to-speech and transcription