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

# Generate images

> Learn how to generate PNG, JPEG, and WebP images from a template with the Bannerify API.

You send one request with a template id and the values to change, and the response body is the image. Bannerify renders the image while the request waits, so you can call it from a request handler, a background job, or a script.

## Prerequisites

* A template. [Template editor](/docs/essentials/template-editor) shows how to build one, and the gallery has ready-made ones.
* An API key. Create one on the **API Keys** page of the dashboard.
* The template id. Open the menu on a template card and choose **Copy Template ID**.

## Generate an image

1. Name the layers you want to change. [Modifications](/docs/essentials/modifications) explains how.
2. Send a `POST` request to `/v1/templates/createImage` with a JSON body:

```bash theme={null}
curl --request POST \
  --url https://api.bannerify.co/v1/templates/createImage \
  --header 'Content-Type: application/json' \
  --output banner.png \
  --data '{
    "apiKey": "YOUR_API_KEY",
    "templateId": "tpl_xxx",
    "modifications": [
      { "name": "headline", "text": "Summer sale" }
    ]
  }'
```

3. Read the response. The body is the image file, and the `Content-Type` header says which format it is: `image/png`, `image/jpeg`, or `image/webp`.

Always send the `Content-Type: application/json` header. A request without it fails with `INTERNAL_SERVER_ERROR`.

## Options

| Field | Type | Default | Description |
| - | - | - | - |
| `apiKey` | string | | Your API key. Required |
| `templateId` | string | | The template to render. Required |
| `modifications` | array, object, or JSON string | `[]` | The values to change. See [Modifications](/docs/essentials/modifications) |
| `format` | `png`, `jpeg`, or `webp` | `png` | The image format. The value is case-sensitive, so `jpg` and `JPEG` fail |
| `quality` | integer from 1 to 100 | `90` | The encoder quality for `jpeg` and `webp`. `png` ignores it |

The template sets the size of the image. A request cannot change the canvas.

PNG is lossless. JPEG and WebP make smaller files, and `quality` sets the trade-off between size and detail.

## Try a template in the dashboard

The **Form** page under **Generate** lets you test a template without code. Its title is **Template Playground**.

1. Choose a template in **Select Template** and a key in **API Key**. The page uses your first key until you choose another.
2. Pick a layer under **Elements**. For a text layer, change **Text Content** on the **Content** tab or **Text Color** on the **Style** tab. For an image layer, enter an **Image URL**. The eye button next to a layer hides it.
3. Click **Generate Preview**.

The page sends a real `createImage` request with the key you chose, so each preview counts as one generation. **Download** saves the PNG, and **Copy** puts it on the clipboard.

<Frame caption="The Template Playground.">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/bannerify/images/docs/form.webp" alt="The Template Playground with the layers of a template on the left and the generated preview on the right" />
</Frame>

## See your generations

The **Generations** page in the sidebar lists every image and PDF that the API made for your project, newest first. This is useful when you want to check what a request sent, or find a stored file again.

* Filter the list by **Template** and by **Time range**: the last 24 hours, 7 days, or 30 days.
* Each row shows the time, the template, the format, the size, and if the generation was billed.
* **Open** opens a stored file. A file that the API returned in the response shows **Not stored**.
* **Copy modifications** copies the values that the request sent, ready to send again.
* **Load more** shows older generations.

<Frame caption="The Generations page.">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/bannerify/images/docs/generations.webp" alt="The Generations page with the renders of the last 7 days, newest first" />
</Frame>

## Get a link instead of a file

`POST /v1/templates/createStoredImage` takes the same body and returns a URL in place of the bytes:

```json theme={null}
{
  "url": "https://images.bannerify.co/files/0b3c1c1e-5d6f-4c52-9e0a-8f6a4c0f2a11.png"
}
```

Bannerify saves the file and serves it from its CDN at a public URL. This is useful when you want to put the link in an email, a database row, or a no-code tool. On the Scale and Enterprise plans you can also send an `s3Config` object to save the file to your own S3-compatible bucket. [Storage and notifications](/docs/integrations/storage-and-notifications) lists its fields.

A stored image counts as one generation.

## Use an SDK

The SDKs send this request for you and return the bytes.

| Language | Page |
| - | - |
| JavaScript | [Create images and PDFs](/docs/sdk/js/apis/create-image) |
| Python | [Create images and PDFs](/docs/sdk/python/apis/create-image) |
| PHP | [Create images and PDFs](/docs/sdk/php/apis/create-image) |
| Go | [Create images and PDFs](/docs/sdk/go/apis/create-image) |

## Handle errors

A failed request returns JSON with an `error` object instead of an image. Read `error.code` to decide what to do next, and send `error.requestId` to support when you need help. [Errors](/docs/api-reference/errors/introduction) lists every code.

## Related pages

* [Generate PDFs](/docs/essentials/generate-pdfs) for invoices, receipts, and certificates.
* [Generate images from a spreadsheet](/docs/essentials/bulk-generation) to fill a template from a CSV or XLSX file.
* [Signed URLs](/docs/essentials/signed-urls) for images that render when someone opens a link.
* [Quota and limits](/docs/account/quota) for what counts as a generation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.