> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepshi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Image generation

> Generate images from a text prompt using the OpenAI-compatible images API.

The images API turns a text prompt into an image. It works with the official OpenAI image SDKs, so you can keep your existing setup and just point it at the Deepshi base URL.

| Endpoint                      | What it does                                                              |
| ----------------------------- | ------------------------------------------------------------------------- |
| `POST /v1/images/generations` | Generate an image from a text prompt                                      |
| `POST /v1/images/edits`       | Edit an existing image (see [Image editing](/capabilities/image-editing)) |

New here? Follow the three steps below. You'll have an image saved to disk in a couple of minutes.

## Step 1: Send a request

A request needs just two things: a **`model`** and a **`prompt`**. Browse the available ids on the [image models](/models/image-models) page. `deepshi-banana-pro` is a fast, low-cost default.

```bash curl theme={null}
curl https://api.deepshi.ai/v1/images/generations \
  -H "Authorization: Bearer $DEEPSHI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepshi-banana-pro",
    "prompt": "a serene canal in Venice at sunset"
  }'
```

You get back a JSON body. The image is base64-encoded in `data[0].b64_json`:

```json theme={null}
{
  "created": 1782595538,
  "model": "deepshi-banana-pro",
  "size": "1024x1024",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...", "index": 0 }
  ],
  "usage": {
    "cost": { "total_cost": 0.01 }
  }
}
```

| Field                   | What it is                                                             |
| ----------------------- | ---------------------------------------------------------------------- |
| `data[].b64_json`       | The image, base64-encoded. Decode it to get the file, which is Step 2. |
| `data[].index`          | The image's position in the batch, starting at `0`.                    |
| `size`                  | The actual output dimensions, as `WIDTHxHEIGHT`.                       |
| `usage.cost.total_cost` | The exact amount, in USD, charged for this request.                    |

## Step 2: Save the image

Decode `b64_json` and write it to a file. With the OpenAI SDK that's just a few lines:

<CodeGroup>
  ```python Python theme={null}
  import base64
  from openai import OpenAI

  client = OpenAI(base_url="https://api.deepshi.ai/v1", api_key="YOUR_DEEPSHI_API_KEY")

  resp = client.images.generate(
      model="deepshi-banana-pro",
      prompt="a serene canal in Venice at sunset",
  )

  with open("output.png", "wb") as f:
      f.write(base64.b64decode(resp.data[0].b64_json))
  print("saved output.png")
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";
  import { writeFileSync } from "node:fs";

  const client = new OpenAI({
    baseURL: "https://api.deepshi.ai/v1",
    apiKey: process.env.DEEPSHI_API_KEY,
  });

  const resp = await client.images.generate({
    model: "deepshi-banana-pro",
    prompt: "a serene canal in Venice at sunset",
  });

  writeFileSync("output.png", Buffer.from(resp.data[0].b64_json, "base64"));
  console.log("saved output.png");
  ```
</CodeGroup>

## Step 3: Set the image size

Models size their output in different ways. Send the field or fields your chosen model supports:

* **Pixel dimensions:** exact `width` and `height`. Examples: `deepshi-banana-pro`, `flux-2-pro`.
* **Resolution tier:** an `aspect_ratio` plus a `resolution` like `1K`, `2K`, or `4K`. Examples: `nano-banana-2`, `nano-banana-pro`.
* **Aspect ratio:** just an `aspect_ratio` like `16:9`. Example: `grok-imagine`.
* **Preset size:** a named `image_size` like `auto_2K` or `1024x1024`. Examples: `seedream-4.5`, `gpt-image-2`.

```json Pixel-dimension model theme={null}
{
  "model": "deepshi-banana-pro",
  "prompt": "a serene canal in Venice at sunset",
  "width": 1024,
  "height": 1024
}
```

```json Resolution-tier model theme={null}
{
  "model": "nano-banana-pro",
  "prompt": "a serene canal in Venice at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
```

<Note>
  Not sure which fields a model takes? See [Choosing a model](#choosing-a-model) below. Every
  model lists its sizing fields in `GET /v1/models`. A model ignores fields it doesn't support,
  so don't carry one model's sizing style over to another.
</Note>

That's the full loop: send a prompt, read the response, save the file. The rest of this page covers picking a model and pricing. To edit an existing image, see [Image editing](/capabilities/image-editing).

## Choosing a model

Each image model supports different parameters, sizing styles, and limits. There are two ways to see them:

* The [image models](/models/image-models) page, with a card per model showing its sizing style, prompt limit, and editing support.
* `GET /v1/models`, the same facts as JSON, scoped to your key (you only see models your key can call).

```bash theme={null}
curl https://api.deepshi.ai/v1/models \
  -H "Authorization: Bearer $DEEPSHI_API_KEY"
```

Each image entry lists the `parameters` it accepts (with `type`, allowed `values`, and `default`), plus an `edit` block, `prompt_max_length`, and its modalities:

```json Example image model entry theme={null}
{
  "id": "nano-banana-pro",
  "object": "model",
  "owned_by": "deepshi",
  "parameters": {
    "resolution":   { "type": "enum", "values": ["1K", "2K", "4K"],             "default": "2K" },
    "aspect_ratio": { "type": "enum", "values": ["auto", "16:9", "1:1", "9:16"], "default": "auto" }
  },
  "edit": { "supported": true, "max_reference_images": 14 },
  "prompt_max_length": 50000,
  "input_modalities": ["text"],
  "output_modalities": ["image"]
}
```

### Common parameters

These apply across image models. Anything else you send is passed straight to the model and only takes effect if that model supports it.

| Parameter         | Type    | Description                                                                                                                            |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `model`           | string  | The image model id. **Required.**                                                                                                      |
| `prompt`          | string  | What to generate. **Required.** Each model caps the length (8,000 to 50,000 characters); over the limit returns `400 PROMPT_TOO_LONG`. |
| `n`               | integer | Number of images (1 to 4). Defaults to `1`. `deepshi-banana-pro` and `deepshi-image-1` support only `n: 1`.                            |
| `response_format` | string  | `b64_json` (default) or `url` (an inline `data:` URI).                                                                                 |
| `output_format`   | string  | `png`, `jpeg`, or `webp` (per model; some support only `png` or `jpeg`).                                                               |
| `quality`         | string  | For the GPT Image models: `low`, `medium`, or `high`. Higher tiers cost more. Other models ignore it.                                  |
| `seed`            | integer | Seed for reproducible output. Omit for a random seed. Supported by some models.                                                        |
| `stream`          | boolean | Stream the result as Server-Sent Events. See [Long-running generations](#long-running-generations).                                    |

## Pricing

Image pricing is per image for most models, and per megapixel for a few. For many models it depends on what you request, such as the `resolution`, `quality`, or output size.

You never calculate this yourself. Every response includes `usage.cost.total_cost` in USD, the exact amount deducted from your balance. Per-model prices are listed on [deepshi.ai](https://deepshi.ai/).

## Long-running generations

High-resolution generations can take a while. For a slow generation, set `stream: true` to receive the result as Server-Sent Events instead of one buffered response. Streamed generations bill exactly the same. See [Streaming](/capabilities/streaming).

## Next steps

<CardGroup cols={2}>
  <Card title="Image editing" icon="pen" href="/capabilities/image-editing">
    Edit an existing image with a prompt.
  </Card>

  <Card title="Image models" icon="image" href="/models/image-models">
    Browse image models and their sizing options.
  </Card>
</CardGroup>