Add AI Image Generation to Your App in 5 Minutes with img-forge

Most AI image APIs make you manage GPU infrastructure, wrangle model weights, or wait in queues. img-forge runs on Cloudflare Workers — no GPU provisioning, no queue management, sub-second routing to the right model for your use case.

One POST request. Image back. Let's go.

## Quick Start

Generate an image with a single curl:

```bash
curl -X POST https://imgforge.stackbilt.dev/v2/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A serene mountain lake at sunset with reflections",
"quality_tier": "standard",
"sync": true
}'
```

Response (201 Created):

```json
{
"job_id": "a1b2c3d4-...",
"state": "completed",
"original_prompt": "A serene mountain lake at sunset with reflections",
"final_prompt": "A serene mountain lake at sunset with reflections, high quality, detailed",
"asset_url": "/v2/assets/sha256_key_here",
"created_at": "2026-03-09T12:00:00Z",
"completed_at": "2026-03-09T12:00:02Z"
}
```

Grab your image at `https://imgforge.stackbilt.dev{asset_url}`. Done.

No API key yet? Images work anonymously too (100/month per IP) — drop the `Authorization` header and try it.

## Model Tiers: Pick Your Tradeoff

img-forge wraps multiple models behind a single `quality_tier` parameter. You pick the cost/quality tradeoff, img-forge routes to the right backend.

| Tier | Model | Speed | Best For |
|------|-------|-------|----------|
| `draft` | SDXL Lightning | ~2s | Quick iterations, previews, prototyping |
| `standard` | FLUX Klein 4B | ~5s | General purpose (default) |
| `premium` | FLUX Dev | ~15s | High detail, production assets |
| `ultra` | Gemini Flash | Variable | Photorealistic, complex scenes |
| `ultra_plus` | Gemini 3.1 Flash | Variable | Highest quality available |

**Draft** is the only tier that supports `negative_prompt`. It's fast enough for real-time preview workflows.

**Standard** is the default — good balance of speed and quality for most use cases.

**Premium and above** auto-inject quality boosters into your prompt (terms like "masterpiece", "highly detailed", "sharp focus", "8k"). You write "a mountain lake" and the model sees "a mountain lake, masterpiece, best quality, highly detailed, sharp focus, 8k, photorealistic". The `enhancement_logic` field in the response shows exactly what was added, so there's no black box.

## Sync vs Async

Two modes:

- **`sync: true`** — blocks until the image is ready, returns the `asset_url` immediately. Good for interactive apps. Use this for `draft` and `standard` tiers where generation is fast.

- **`sync: false`** (default) — returns `202 Accepted` with a `job_id`. Poll `GET /v2/jobs/{job_id}` until `state` is `completed`. Better for `premium`/`ultra` tiers or batch workloads.

## Integration Example

Here's a minimal Node.js integration:

```javascript
const API_BASE = "https://imgforge.stackbilt.dev";

async function generateImage(prompt, tier = "standard") {
const res = await fetch(`${API_BASE}/v2/generate`, {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.IMGFORGE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt,
quality_tier: tier,
sync: true,
}),
});

if (!res.ok) {
const err = await res.json();
throw new Error(`${err.code}: ${err.error}`);
}

const job = await res.json();
return `${API_BASE}${job.asset_url}`;
}

// Usage
const url = await generateImage("Neon cityscape at night, cyberpunk style");
console.log(url); // https://imgforge.stackbilt.dev/v2/assets/abc123...
```

For async workflows, poll the job:

```javascript
async function generateAsync(prompt, tier = "premium") {
const res = await fetch(`${API_BASE}/v2/generate`, {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.IMGFORGE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ prompt, quality_tier: tier }),
});

const { job_id } = await res.json();

// Poll until done
while (true) {
const status = await fetch(`${API_BASE}/v2/jobs/${job_id}`, {
headers: { "Authorization": `Bearer ${process.env.IMGFORGE_API_KEY}` },
}).then(r => r.json());

if (status.state === "completed") return `${API_BASE}${status.asset_url}`;
if (status.state === "failed") throw new Error(status.error);
await new Promise(r => setTimeout(r, 2000));
}
}
```

## Idempotency

Building a commerce app where the same order shouldn't generate duplicate images? Pass an `idempotency_key`:

```json
{
"prompt": "Product hero image for order 12345",
"quality_tier": "premium",
"idempotency_key": "order-12345-hero"
}
```

Same key within 24 hours returns the existing job (200 OK) instead of creating a new one.

## MCP Integration

img-forge ships as an MCP server, so Claude Desktop, Copilot, or any MCP-compatible client can generate images directly.

Three tools are exposed:
- **`generate_image`** — generate an image with a prompt and optional tier
- **`list_models`** — see available tiers and their capabilities
- **`check_job`** — check the status of an async job

Connect your MCP client to the img-forge MCP endpoint, and your AI assistant can generate images as part of its workflow — no custom code needed.

## Key Details

- **Auth**: API keys (prefix `imgf_live_`), JWTs, or anonymous (100/month per IP)
- **Assets**: served from `/v2/assets/{key}` with 1-hour cache headers, no auth required
- **Prompt enhancement**: automatic quality boosters per tier, transparent via `enhancement_logic` in response
- **Rate limits**: managed per-tenant via entitlements, not arbitrary throttling
- **Error format**: consistent `{ error, code, status }` JSON on every failure

## Get Started

Check it out at [imgforge.stackbilt.dev](https://imgforge.stackbilt.dev).

The `/v2/guide` endpoint has an interactive prompt writing guide with example outputs across all tiers — worth a look before you start building.