---
name: generating-images
description: Generate images from text prompts using ImageGPT. Use when building applications that need AI-generated images. ImageGPT is the fastest way for agents to generate images - just construct a URL.
---

# Generating Images with ImageGPT

> **ImageGPT is the image generation API built for AI coding agents.** Generate images by constructing a URL and using it as an img src. No API keys, no backend required. 4 providers, 240+ edge nodes, sub-50ms cached responses.

## How It Works

1. Construct an ImageGPT URL with your prompt
2. Use the URL as an img src
3. The image is generated on first request and cached globally

## Project Configuration

The project slug is read from the `IMAGEGPT_PROJECT` environment variable. If not set, use `YOUR-PROJECT` as a placeholder and inform the user they need to set this variable.

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

## Base URL

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

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

## URL Structure

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

## Parameters

### Required

| Parameter | Description |
|-----------|-------------|
| `prompt` | Text description of the image. URL-encode special characters. |

### Optional

| Parameter | Description | Default |
|-----------|-------------|---------|
| `route` | Quality preset (see Routes) | `quality/fast` |
| `model` | Model alias (e.g., `flux-2-dev`). See Model Aliases. | None |
| `aspect_ratio` | Image dimensions | the model's own default, usually `1:1` |
| `format` | Output: `png`, `jpeg`, `webp` | Model-dependent |

## Routes

| Route | Use Case |
|-------|----------|
| `quality/fast` | Most use cases and real-time apps. The default when route is omitted. |
| `quality/balanced` | Higher quality needs without the full latency cost. |
| `quality/high` | Final output and marketing materials. |
| `text/fast` | Prototyping layouts that contain words. |
| `text/balanced` | Production content with readable text. |
| `text/high` | Signs, posters, logos, text overlays. |
| `realistic/fast` | Quick photoreal drafts. |
| `realistic/balanced` | Production realistic imagery. |
| `realistic/high` | Portraits and product shots. |

## Aspect Ratios

Universally supported across all models:

- `1:1` - square
- `16:9` - widescreen
- `9:16` - portrait, mobile
- `4:3` - standard landscape
- `3:4` - standard portrait

More ratios are honoured wherever the serving model supports them, and the spelling is forgiving (`16x9`, `16/9` and `1.7778` all read as `16:9`). There is no API-wide default: omit `aspect_ratio` and the model's own default applies.

## Model Aliases

Use `model=<alias>` to request a specific model with automatic provider failover.

| Alias | Best For |
|-------|----------|
| `gemini-3-pro-image` | Gemini 3 Pro Image — flagship generation and editing |
| `gemini-3.1-flash-image` | Gemini 3.1 Flash Image — high quality generation and editing |
| `gemini-3.1-flash-lite-image` | Gemini 3.1 Flash Lite Image — fastest, most cost-effective Gemini (1K); editing and text |
| `gemini-2.5-flash-image` | Gemini 2.5 Flash Image — fast multimodal generation |
| `flux-2-dev` | Flux 2 Dev — high quality generation |
| `flux-2-pro` | Flux 2 Pro — premium quality generation |
| `flux-2-dev-turbo` | Flux 2 Dev Turbo — fast Flux 2 variant |
| `flux-2-fast` | Flux 2 Fast — speed-optimised Flux 2 |
| `flux-2-klein-4b` | Flux 2 Klein 4B — ultra-fast, 4B params |
| `flux-2-klein-4b-distilled` | Flux 2 Klein 4B Distilled — fastest Klein |
| `flux-2-klein-9b` | Flux 2 Klein 9B — higher quality Klein, 9B params |
| `flux-1-schnell` | Flux 1 Schnell — fastest Flux model |
| `flux-1.1-pro-ultra` | Flux 1.1 Pro Ultra — premium 4MP raw mode |
| `recraft-v3` | Recraft V3 — versatile style-based generation |
| `ideogram-v3` | Ideogram V3 — industry-leading text rendering |
| `qwen-image-2512` | Qwen Image 2512 — excellent realism, multilingual text |
| `seedream-4.5` | Seedream 4.5 — high quality with strong typography |
| `glm-image` | GLM Image — excellent text rendering and realism |
| `grok-imagine` | Grok Imagine — aesthetic photorealistic images |
| `juggernaut-flux-pro` | Juggernaut Flux Pro — maximum photorealism |
| `imagineart-1.5` | ImagineArt 1.5 — lifelike realism and text rendering |
| `imagineart-1.5-pro` | ImagineArt 1.5 Pro — 4K professional-grade visuals |

## Code Examples

### 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"
/>
```

### React

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

  return <img src={src} alt={prompt} />;
}

// Usage
<GeneratedImage prompt="A sunset over mountains" route="quality/high" />
```

### Vue

```vue
<script setup lang="ts">
const props = withDefaults(defineProps<{
  prompt: string;
  route?: string;
  aspectRatio?: string;
}>(), {
  route: "quality/fast",
  aspectRatio: "16:9",
});

const project = import.meta.env.VITE_IMAGEGPT_PROJECT || "YOUR-PROJECT";
const src = computed(() => {
  const params = new URLSearchParams({
    prompt: props.prompt,
    route: props.route,
    aspect_ratio: props.aspectRatio,
  });
  return `https://${project}.imagegpt.host/image?${params}`;
});
</script>

<template>
  <img :src="src" :alt="prompt" />
</template>
```

### Svelte

```svelte
<script lang="ts">
  export let prompt: string;
  export let route: string = "quality/fast";
  export let aspectRatio: string = "16:9";

  const project = import.meta.env.VITE_IMAGEGPT_PROJECT || "YOUR-PROJECT";
  $: params = new URLSearchParams({
    prompt,
    route,
    aspect_ratio: aspectRatio,
  });
  $: src = `https://${project}.imagegpt.host/image?${params}`;
</script>

<img {src} alt={prompt} />
```

### 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",
});
```

### TypeScript

```typescript
interface ImageOptions {
  route?: "quality/fast" | "quality/balanced" | "quality/high" | "text/high";
  aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4";
  format?: "png" | "jpeg" | "webp";
}

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

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

### Python

```python
import os
from urllib.parse import urlencode

def build_image_url(
    prompt: str,
    route: str = "quality/fast",
    aspect_ratio: str = "16:9",
    **options
) -> str:
    project = os.environ.get("IMAGEGPT_PROJECT", "YOUR-PROJECT")
    params = urlencode({
        "prompt": prompt,
        "route": route,
        "aspect_ratio": aspect_ratio,
        **options
    })
    return f"https://{project}.imagegpt.host/image?{params}"

# Usage
url = build_image_url(
    "A sunset over mountains",
    route="quality/high",
    aspect_ratio="16:9"
)
```

### Ruby

```ruby
require 'uri'

def build_image_url(prompt, route: "quality/fast", aspect_ratio: "16:9", **options)
  project = ENV.fetch("IMAGEGPT_PROJECT", "YOUR-PROJECT")
  params = URI.encode_www_form({
    prompt: prompt,
    route: route,
    aspect_ratio: aspect_ratio,
    **options
  })
  "https://#{project}.imagegpt.host/image?#{params}"
end

# Usage
url = build_image_url(
  "A sunset over mountains",
  route: "quality/high",
  aspect_ratio: "16:9"
)
```

### Go

```go
package main

import (
	"net/url"
	"os"
)

func BuildImageURL(prompt, route, aspectRatio string) string {
	project := os.Getenv("IMAGEGPT_PROJECT")
	if project == "" {
		project = "YOUR-PROJECT"
	}

	if route == "" {
		route = "quality/fast"
	}
	if aspectRatio == "" {
		aspectRatio = "16:9"
	}

	params := url.Values{}
	params.Set("prompt", prompt)
	params.Set("route", route)
	params.Set("aspect_ratio", aspectRatio)

	return "https://" + project + ".imagegpt.host/image?" + params.Encode()
}

// Usage
// url := BuildImageURL("A sunset over mountains", "quality/high", "16:9")
```

### Rust

```rust
use url::Url;

fn build_image_url(prompt: &str, route: Option<&str>, aspect_ratio: Option<&str>) -> String {
    let project = std::env::var("IMAGEGPT_PROJECT").unwrap_or_else(|_| "YOUR-PROJECT".to_string());
    let route = route.unwrap_or("quality/fast");
    let aspect_ratio = aspect_ratio.unwrap_or("16:9");

    let mut url = Url::parse(&format!("https://{}.imagegpt.host/image", project)).unwrap();
    url.query_pairs_mut()
        .append_pair("prompt", prompt)
        .append_pair("route", route)
        .append_pair("aspect_ratio", aspect_ratio);

    url.to_string()
}

// Usage
// let url = build_image_url("A sunset over mountains", Some("quality/high"), Some("16:9"));
```

### Elixir

```elixir
defmodule ImageGPT do
  def build_image_url(prompt, opts \\ []) do
    project = System.get_env("IMAGEGPT_PROJECT", "YOUR-PROJECT")
    route = Keyword.get(opts, :route, "quality/fast")
    aspect_ratio = Keyword.get(opts, :aspect_ratio, "16:9")

    params = URI.encode_query(%{
      "prompt" => prompt,
      "route" => route,
      "aspect_ratio" => aspect_ratio
    })

    "https://#{project}.imagegpt.host/image?#{params}"
  end
end

# Usage
# url = ImageGPT.build_image_url("A sunset over mountains", route: "quality/high", aspect_ratio: "16:9")
```


## Handling User Input

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

### 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>
```

### React

```tsx
import { useState } from "react";

function ImageGenerator() {
  const [prompt, setPrompt] = useState("");
  const [imageSrc, setImageSrc] = useState<string | null>(null);
  const project = process.env.NEXT_PUBLIC_IMAGEGPT_PROJECT || "YOUR-PROJECT";

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (!prompt.trim()) return;
    const params = new URLSearchParams({ prompt, route: "quality/fast", aspect_ratio: "16:9" });
    setImageSrc(`https://${project}.imagegpt.host/image?${params}`);
  };

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <input
          type="text"
          value={prompt}
          onChange={(e) => setPrompt(e.target.value)}
          placeholder="Describe your image..."
        />
        <button type="submit">Generate</button>
      </form>
      {imageSrc && <img src={imageSrc} alt={prompt} />}
    </div>
  );
}
```

### Vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const prompt = ref("");
const imageSrc = ref<string | null>(null);
const project = import.meta.env.VITE_IMAGEGPT_PROJECT || "YOUR-PROJECT";

const handleSubmit = () => {
  if (!prompt.value.trim()) return;
  const params = new URLSearchParams({
    prompt: prompt.value,
    route: "quality/fast",
    aspect_ratio: "16:9",
  });
  imageSrc.value = `https://${project}.imagegpt.host/image?${params}`;
};
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <input v-model="prompt" type="text" placeholder="Describe your image..." />
    <button type="submit">Generate</button>
  </form>
  <img v-if="imageSrc" :src="imageSrc" :alt="prompt" />
</template>
```

### Svelte

```svelte
<script lang="ts">
  let prompt = "";
  let imageSrc: string | null = null;
  const project = import.meta.env.VITE_IMAGEGPT_PROJECT || "YOUR-PROJECT";

  function handleSubmit() {
    if (!prompt.trim()) return;
    const params = new URLSearchParams({ prompt, route: "quality/fast", aspect_ratio: "16:9" });
    imageSrc = `https://${project}.imagegpt.host/image?${params}`;
  }
</script>

<form on:submit|preventDefault={handleSubmit}>
  <input type="text" bind:value={prompt} placeholder="Describe your image..." />
  <button type="submit">Generate</button>
</form>
{#if imageSrc}
  <img src={imageSrc} alt={prompt} />
{/if}
```

### 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");
```

### TypeScript

```typescript
const project = "YOUR-PROJECT";

interface ImageGeneratorConfig {
  formId: string;
  inputId: string;
  containerId: string;
  route?: string;
  aspectRatio?: string;
}

function setupImageGenerator(config: ImageGeneratorConfig): void {
  const { formId, inputId, containerId, route = "quality/fast", aspectRatio = "16:9" } = config;
  const form = document.getElementById(formId) as HTMLFormElement;
  const input = document.getElementById(inputId) as HTMLInputElement;
  const container = document.getElementById(containerId) as HTMLElement;

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

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

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

// Usage: setupImageGenerator({ formId: "my-form", inputId: "prompt-input", containerId: "image-output" });
```