image generation

generate images from text prompts

basic usage

import { generateImage } from "@threaded/ai";

const result = await generateImage(
  "openai/dall-e-3",
  "a cat wearing a tiny top hat"
);

const buffer = Buffer.from(result.data, "base64");
writeFileSync("output.png", buffer);

returns { data: string, revisedPrompt?: string }

• data - base64-encoded image data (or url if requested)
• revisedPrompt - the prompt actually used by the model (some providers revise your prompt)

supported providers

openai

dall-e and gpt-image models

await generateImage("openai/dall-e-3", "a sunset over mountains");
await generateImage("openai/dall-e-2", "a sunset over mountains");
await generateImage("openai/gpt-image-1.5", "a sunset over mountains");

xai (grok)

await generateImage("xai/grok-2-image-1212", "a sunset over mountains");

returns jpeg format

google (gemini)

await generateImage("google/gemini-2.5-flash-image", "a sunset over mountains");
await generateImage("google/nano-banana-pro-preview", "a sunset over mountains");

configuration options

pass options as the third argument

await generateImage("openai/dall-e-3", "prompt", {
  size: "1024x1024",
  quality: "hd",
  style: "vivid",
});

common options

option	type	description
n	number	number of images to generate (1-10)
size	string	image dimensions
quality	string	generation quality
responseFormat	string	"url" or "b64_json"

dall-e options

option	values
size	"256x256", "512x512", "1024x1024" (dall-e-2)
	"1024x1024", "1792x1024", "1024x1792" (dall-e-3)
quality	"standard", "hd"
style	"vivid", "natural"

gpt-image options

gpt-image-1, gpt-image-1.5, gpt-image-1-mini

option	values
size	"1024x1024", "1536x1024", "1024x1536", "auto"
quality	"low", "medium", "high", "auto"
outputFormat	"png", "jpeg", "webp"
outputCompression	0-100 (jpeg/webp only)
background	"transparent", "opaque", "auto"

await generateImage("openai/gpt-image-1.5", "a golden crown", {
  size: "1536x1024",
  quality: "high",
  outputFormat: "webp",
  background: "transparent",
});

transparent backgrounds require png or webp format

google options

option	values
aspectRatio	"1:1", "16:9", "9:16", "4:3", "3:4"

await generateImage("google/gemini-2.5-flash-image", "a landscape", {
  aspectRatio: "16:9",
});

revised prompts

some providers (openai, xai) revise your prompt before generating

const result = await generateImage(
  "xai/grok-2-image-1212",
  "a cat in a hat"
);

console.log(result.revisedPrompt);
// "A high-resolution photograph of a gray and white cat
//  wearing a small black top hat, sitting in a plush,
//  red velvet vintage armchair..."

useful for understanding what the model actually generated

saving images

as file

import { writeFileSync } from "fs";

const result = await generateImage("openai/gpt-image-1.5", "prompt");
const buffer = Buffer.from(result.data, "base64");
writeFileSync("output.png", buffer);

compressed jpeg

const result = await generateImage("openai/gpt-image-1.5", "prompt", {
  outputFormat: "jpeg",
  outputCompression: 80,
});

const buffer = Buffer.from(result.data, "base64");
writeFileSync("output.jpg", buffer);

smaller file size, faster generation

api keys

environment variables are detected automatically

provider	env var
openai	OPENAI_API_KEY
xai	XAI_API_KEY
google	GEMINI_API_KEY

or use setKeys() - see quick start

complete example

import { generateImage } from "@threaded/ai";
import { writeFileSync } from "fs";

const providers = [
  { model: "openai/gpt-image-1.5", ext: "png" },
  { model: "xai/grok-2-image-1212", ext: "jpg" },
  { model: "google/nano-banana-pro-preview", ext: "png" },
];

const prompt = "a robot playing chess with a penguin";

for (const { model, ext } of providers) {
  const result = await generateImage(model, prompt);

  const buffer = Buffer.from(result.data, "base64");
  const filename = model.replace("/", "-") + "." + ext;
  writeFileSync(filename, buffer);

  console.log(`${model}: saved to ${filename}`);
  if (result.revisedPrompt) {
    console.log(`  revised: ${result.revisedPrompt.slice(0, 100)}...`);
  }
}

generates same prompt across multiple providers for comparison

next: tool approval