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:

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):

{
  "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.

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:

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:

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:

{
  "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.

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