# 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

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