---
title: puter.ai.txt2img()
description: Generate images from text prompts using AI models like GPT Image, Nano Banana, Grok Image, or FLUX.
platforms: [websites, apps, nodejs, workers]
---

Given a prompt, generate an image using AI.

## Syntax

```js
puter.ai.txt2img(prompt, testMode = false)
puter.ai.txt2img(prompt, options = {})
puter.ai.txt2img({ prompt, ...options })
```

## Parameters

#### `prompt` (String) (required)

A string containing the prompt you want to generate an image from.

#### `testMode` (Boolean) (Optional)

A boolean indicating whether you want to use the test API. Defaults to `false`. This is useful for testing your code without using up API credits.

#### `options` (Object) (Optional)

Additional settings for the generation request. Available options depend on the provider.

| Option | Type | Description |
|--------|------|-------------|
| `prompt` | `String` | Text description for the image generation |
| `provider` | `String` | The AI provider to use. `'openai-image-generation' (default) \| 'gemini' \| 'together' \| 'xai' \| 'replicate-image-generation'` |
| `model` | `String` | Image model to use (provider-specific). Defaults to `'gpt-image-1-mini'` (OpenAI) or `'grok-imagine-image'` when `provider: 'xai'` |
| `test_mode` | `Boolean` | When `true`, returns a sample image without using credits |
| `puter_output_path` | `String` | When set, the generated image is automatically saved to this path on the Puter filesystem. Relative paths are resolved against the app's data directory (or `~/` outside an app). The caller must have write permission to the destination |
| `input_images` | `Array<String>` | Input image(s) for image-to-image — the canonical, cross-provider field (see below). |
| `input_image` | `String` | Single-image shorthand for `input_images`. |

#### Input images (image-to-image)

`input_images` is the universal way to pass image-to-image inputs across providers; `input_image` is the single-image shorthand. Each entry may be a **public URL**, a **data-URI**, or **raw base64** — providers that need base64 fetch URLs server-side (SSRF-guarded), so a URL works everywhere.

| Provider | Multiple images? | Accepted input forms |
|----------|------------------|----------------------|
| OpenAI `gpt-image-*` | Yes | URL, base64 / data-URI |
| Gemini | Yes | URL, base64 / data-URI |
| Replicate | Yes (model-dependent) | URL, base64 / data-URI |
| xAI `grok-imagine-*` | Up to 3 | URL, base64 / data-URI |
| Together | Single only (400 if more than one) | URL, base64 / data-URI |
| Cloudflare | Single only (400 if more than one) | URL, base64 / data-URI (only some models use it) |

#### OpenAI Options

Available when `provider: 'openai-image-generation'` or inferred from model (`gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`):

| Option | Type | Description |
|--------|------|-------------|
| `model` | `String` | Image model to use. Available: `'gpt-image-2'`, `'gpt-image-1.5'`, `'gpt-image-1'`, `'gpt-image-1-mini'` |
| `quality` | `String` | Image quality: `'high'`, `'medium'`, `'low'` (default: `'low'`); `gpt-image-2` also accepts `'auto'` |
| `ratio` | `Object` | Aspect ratio with `w` and `h` properties. `gpt-image-2` accepts arbitrary sizes; other GPT models are restricted to fixed sizes |
| `input_image` | `String` | An input image for image-to-image editing — a URL or base64/data-URI (URLs are fetched server-side). |
| `input_images` | `Array<String>` | Multiple input images (URL or base64/data-URI) for image-to-image editing. Routes the request through OpenAI's image edit endpoint. |

For more details, see the [OpenAI API reference](https://platform.openai.com/docs/api-reference/images/create).

#### Gemini Options

Available when `provider: 'gemini'` or inferred from model:

| Option | Type | Description |
|--------|------|-------------|
| `model` | `String` | Image model to use. |
| `ratio` | `Object` | Aspect ratio as `{ w, h }` (e.g., `{ w: 16, h: 9 }`). |
| `quality` | `String` | Output size tier: `'512'`, `'1K'`, `'2K'`, `'4K'` (availability varies by model) |
| `input_images` | `Array<String>` | Input images for image-to-image — a URL or base64/data-URI (URLs are fetched server-side). |

#### xAI (Grok) Options

Available when `provider: 'xai'` or inferred from model (`grok-imagine-image`, alias `grok-image`):

| Option | Type | Description |
|--------|------|-------------|
| `model` | `String` | Image model to use. Available: `'grok-imagine-image'` (default), `'grok-imagine-image-quality'` |
| `prompt` | `String` | Text prompt for the image (or the edit instruction when input images are supplied). |
| `quality` | `String` | Output resolution tier: `'1k'` (default) or `'2k'`. |
| `input_image` | `String` | A public URL or base64-encoded (data-URI) input image for image-to-image editing. |
| `input_images` | `Array<String>` | Up to 3 input images (URLs or base64/data-URI) for multi-image editing — combine subjects, transfer styles, compose scenes. Routes through xAI's image edit endpoint. |

#### Together Options

Available when `provider: 'together'` or inferred from model:

| Option | Type | Description |
|--------|------|-------------|
| `model` | `String` | The model to use for image generation. |
| `width` | `Number` | Width of the image to generate in number of pixels. Default: `1024` |
| `height` | `Number` | Height of the image to generate in number of pixels. Default: `1024` |
| `aspect_ratio` | `String` | Alternative way to specify aspect ratio |
| `steps` | `Number` | Number of generation steps. Default: `20` |
| `seed` | `Number` | Seed used for generation. Can be used to reproduce image generations |
| `negative_prompt` | `String` | The prompt or prompts not to guide the image generation |
| `n` | `Number` | Number of image results to generate. Default: `1` |
| `input_images` | `Array<String>` | Image-to-image input — **single image only** (400 if more than one). A URL is routed to `image_url`; base64/data-URI to `image_base64`. |
| `input_image` | `String` | Single-image shorthand for `input_images`. |
| `image_url` | `String` | URL of an image to use for image models that support it |
| `image_base64` | `String` | Base64 encoded input image for image-to-image generation |
| `mask_image_url` | `String` | URL of mask image for inpainting |
| `mask_image_base64` | `String` | Base64 encoded mask image for inpainting |
| `prompt_strength` | `Number` | How strongly the prompt influences the output |
| `disable_safety_checker` | `Boolean` | If `true`, disables the safety checker for image generation |
| `response_format` | `String` | Format of the image response. Can be either a base64 string or a URL. Options: `'base64'`, `'url'` |

For more details, see the [Together AI API reference](https://docs.together.ai/reference/post-images-generations).

#### Replicate Options

Available when `provider: 'replicate-image-generation'` or inferred from model:

##### Common options

| Option | Type | Description |
|--------|------|-------------|
| `model` | `String` | Model id (e.g. `'black-forest-labs/flux-schnell'`, `'leonardoai/lucid-origin'`). |
| `ratio` | `Object` | Aspect ratio as `{ w, h }` (e.g., `{ w: 16, h: 9 }`). |
| `input_image` | `String` | Input image for image-to-image generation — a URL or base64/data-URI. |
| `input_images` | `Array<String>` | Input images (URL or base64/data-URI) for multi-image generation. |

##### Per-model options

These keys are only forwarded for models that whitelist them (see per-model `allowed_params`):

| Option | Type | Models | Description |
|--------|------|--------|-------------|
| `seed` | `Number` | most models | Random seed for reproducible generation. |
| `steps` | `Number` | `flux-schnell` | Number of inference steps. |
| `guidance` | `Number` | `flux-2-klein-9b-base` | Guidance scale. |
| `go_fast` | `Boolean` | `flux-2-dev` | Use optimized fast mode. Defaults to `true` for `flux-2-dev`; affects pricing. |
| `output_quality` | `Number` | flux family | Output quality (0–100). |
| `output_megapixels` | `String` | flux family | Approximate output megapixels (e.g. `'0.25'`, `'0.5'`, `'1'`, `'2'`). |
| `disable_safety_checker` | `Boolean` | flux-2-dev / klein / flux-schnell | If `true`, disables the safety checker. |
| `safety_tolerance` | `Number` | `flux-2-pro`, `flux-1.1-pro` | Safety tolerance level. |
| `prompt_upsampling` | `Boolean` | `flux-1.1-pro` | Enable prompt upsampling. |
| `response_format` | `String` | most models | Output format (e.g. `'webp'`, `'jpg'`, `'png'`). |
| `generation_mode` | `String` | Leonardo (`lucid-origin`, `phoenix-1.0`) | Generation tier — affects pricing. e.g. `'standard'`/`'ultra'` (lucid-origin), `'fast'`/`'quality'`/`'ultra'` (phoenix-1.0). |
| `style` | `String` | Leonardo | Stylistic preset. |
| `contrast` | `String` | Leonardo | Contrast preset. |
| `prompt_enhance` | `Boolean` | Leonardo | Server-side prompt enhancement. |

For more details, see the [Replicate API reference](https://replicate.com/docs) and each model's schema page on Replicate.

Any properties not set fall back to provider defaults.

#### Saving to Puter filesystem

Pass `puter_output_path` to persist the generated image directly on the Puter filesystem. Relative paths are resolved against `~/AppData/<appID>/` when called from an app, or `~/` otherwise:

```js
puter.ai.txt2img("A sunset over the mountains", {
    puter_output_path: "images/sunset.png"  // saved to ~/AppData/<appID>/images/sunset.png
});
```

Absolute paths (`/username/Pictures/sunset.png`) and home-relative paths (`~/Pictures/sunset.png`) are sent as-is. Write permission to the destination is enforced server-side.

## Return value

A `Promise` that resolves to an `HTMLImageElement`. The element’s `src` points at a data URL containing the image.

## Examples

<strong class="example-title">Generate an image of a cat using AI</strong>

```html;ai-txt2img
<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        // Generate an image of a cat using the default model and quality. Please note that testMode is set to true so that you can test this code without using up API credits.
        puter.ai.txt2img('A picture of a cat.', true).then((image)=>{
            document.body.appendChild(image);
        });
    </script>
</body>
</html>
```

<strong class="example-title">Generate an image with specific model and quality</strong>

```html;ai-txt2img-options
<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        // Generate an image of a cat playing piano using a specific model and quality set to low
        puter.ai.txt2img("a cat playing the piano", {
            model: "gpt-image-2",
            quality: "low"
        }).then((image)=>{
            document.body.appendChild(image);
        });
    </script>
</body>
</html>
```

<strong class="example-title">Generate an image with image-to-image generation</strong>

```html;ai-txt2img-image-to-image
<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.ai.txt2img("a cat playing piano", {
            model: "gemini-3.1-flash-image-preview",
            input_image: " ",
            input_image_mime_type: "image/png"
        }).then((image)=>{
            document.body.appendChild(image);
        });
    </script>
</body>
</html>
```
