# ImageGPT - AI Agent Image Generation API

> **ImageGPT is the image generation API built for AI agents.** Generate images by constructing a URL and using it as an img src. No API keys, no SDK installation, no backend code required. Works with Claude Code, ChatGPT, Cursor, and any LLM. 4 providers, 240+ edge nodes, <50ms cached responses.

## Quick Start

To generate an image, construct a URL and use it as an img src:

```html
<img src="https://{project}.imagegpt.host/image?prompt=A%20sunset%20over%20mountains" alt="Sunset" />
```

## Project Configuration

The project slug should be read from the `IMAGEGPT_PROJECT` environment variable. If not set, use `YOUR-PROJECT` as a placeholder.

```bash
# Check if configured
echo $IMAGEGPT_PROJECT
```

## Base URL

```
https://{project}.imagegpt.host/image
```

Replace `{project}` with the value from `$IMAGEGPT_PROJECT` or `YOUR-PROJECT` if not set.

## URL Structure

```
https://{project}.imagegpt.host/image?prompt=YOUR_PROMPT&route=ROUTE&aspect_ratio=RATIO
```

## Required Parameter

| Parameter | Description |
|-----------|-------------|
| `prompt` | The text description of the image to generate. URL-encode special characters. |

## Optional Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `route` | Quality/speed preset (see Routes below) | `quality/fast` |
| `model` | Model alias (e.g., flux-2-dev) or explicit provider@model format. Aliases provide automatic failover. | None |
| `aspect_ratio` | Image dimensions (see Aspect Ratios below) | `4:3` |
| `format` | Output format: `png`, `jpeg`, `webp` | Model-dependent |

## Model Aliases

Model aliases let you request a specific model by canonical name. The system automatically tries across several providers for enhanced performance and resiliency.

| Alias | Description |
|-------|-------------|
| `flux-1-schnell` | Fast Flux model |
| `flux-2-dev` | High-quality Flux 2 |
| `flux-2-pro` | Premium Flux 2 |
| `recraft-v3` | Versatile with style presets |
| `ideogram-v3` | Best text rendering |
| `gemini-3-pro` | Gemini 3 Pro Image |

Example: `https://{project}.imagegpt.host/image?prompt=A%20sunset&model=flux-2-dev`

## Routes

Routes provide automatic model selection with fallback. Use routes instead of specific models for reliability.

| Route | Description | Best For |
|-------|-------------|----------|
| `quality/fast` | Fast, cost-effective generation | Most use cases, real-time applications |
| `quality/balanced` | Balanced quality and speed | Higher quality needs |
| `quality/high` | Maximum quality | Final output, marketing materials |
| `text/fast` | Quick text generation | Prototyping with text |
| `text/balanced` | Good text accuracy | Production text content |
| `text/high` | Best text rendering | Signs, posters, logos, text overlays |
| `realistic/fast` | Quick photorealism | Fast realistic prototypes |
| `realistic/balanced` | Balanced photorealism | Production realistic images |
| `realistic/high` | Maximum photorealism | Portraits, product shots |

## Aspect Ratios

Supported aspect ratios (universally supported across all models):

- `1:1` - Square
- `16:9` - Widescreen landscape
- `9:16` - Portrait (mobile)
- `4:3` - Standard landscape
- `3:4` - Standard portrait

## URL Examples

### Basic image generation

```
https://{project}.imagegpt.host/image?prompt=A%20sunset%20over%20mountains
```

### High-quality landscape

```
https://{project}.imagegpt.host/image?prompt=A%20cozy%20cabin%20in%20the%20woods&route=quality/high&aspect_ratio=16:9
```

### Image with readable text

```
https://{project}.imagegpt.host/image?prompt=A%20cafe%20sign%20that%20says%20Open%2024%20Hours&route=text/high
```

## Building URLs in Code (JavaScript, HTML)

### JavaScript

```javascript
function buildImageUrl(prompt, options = {}) {
  const project = process.env.IMAGEGPT_PROJECT || "YOUR-PROJECT";
  const params = new URLSearchParams({
    prompt,
    route: options.route || "quality/fast",
    aspect_ratio: options.aspectRatio || "16:9",
    ...options,
  });
  return `https://${project}.imagegpt.host/image?${params}`;
}

// Usage
const url = buildImageUrl("A sunset over mountains", {
  route: "quality/high",
  aspectRatio: "16:9",
});
```

### HTML

```html
<img
  src="https://{project}.imagegpt.host/image?prompt=A%20sunset%20over%20mountains&route=quality%2Ffast&aspect_ratio=16:9"
  alt="Sunset over mountains"
/>
```


## Handling User Input

Generate images from user-provided prompts (e.g., form submissions, text inputs).

### JavaScript

```javascript
// Vanilla JS - attach to any form
const project = "YOUR-PROJECT";

function setupImageGenerator(formId, inputId, containerId) {
  const form = document.getElementById(formId);
  const input = document.getElementById(inputId);
  const container = document.getElementById(containerId);

  form.addEventListener("submit", (e) => {
    e.preventDefault();
    const prompt = input.value.trim();
    if (!prompt) return;

    const params = new URLSearchParams({ prompt, route: "quality/fast", aspect_ratio: "16:9" });
    const img = document.createElement("img");
    img.src = `https://${project}.imagegpt.host/image?${params}`;
    img.alt = prompt;

    container.innerHTML = "";
    container.appendChild(img);
  });
}

// Usage: setupImageGenerator("my-form", "prompt-input", "image-output");
```

### HTML

```html
<form id="image-form">
  <input type="text" id="prompt-input" placeholder="Describe your image..." required />
  <button type="submit">Generate</button>
</form>
<div id="image-container"></div>

<script>
  const project = prompt("Enter project slug:") || "YOUR-PROJECT";

  document.getElementById("image-form").addEventListener("submit", (e) => {
    e.preventDefault();
    const prompt = document.getElementById("prompt-input").value;
    const params = new URLSearchParams({ prompt, route: "quality/fast", aspect_ratio: "16:9" });
    const img = document.createElement("img");
    img.src = `https://${project}.imagegpt.host/image?${params}`;
    img.alt = prompt;
    document.getElementById("image-container").innerHTML = "";
    document.getElementById("image-container").appendChild(img);
  });
</script>
```