---
title: "Generate image from template"
method: POST
path: "/v1/image/create"
tags: ["Image"]
---

# Generate image from template

`POST /v1/image/create`

Generate an image (PNG, JPEG or WebP) from an image template.

**Authentication:** API Key required (`x-api-key` header)

## Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `template_id` | string | ✅ Yes | Template short ID (12 characters) |
| `modifications` | array | No | Modify elements by layer name (see below) |
| `format` | string | No | `png` (default), `jpeg` or `webp` |
| `width` | integer | No | Output width in pixels (defaults to the template's native width) |
| `export_type` | string | No | `url` (default) or `binary` |

## Modifications

Each modification targets a layer by the `name` you set in the editor's Layers panel:

| Property | Description |
|----------|-------------|
| `name` | Layer name to modify (required) |
| `text` | Replace the layer's text |
| `image_url` | Set the layer's image (`src` for images, `background-image` otherwise) |
| `color` | Text color |
| `background` | Background color |
| `hidden` | Hide (`true`) or show (`false`) the layer |

Unknown layer names are skipped and listed in the response `warnings`. A name that
matches several layers is applied to all of them.

## Export Types
- `url` (default): image is uploaded to CDN, returns JSON with URL
- `binary`: returns raw image bytes directly

**Note:** This endpoint only accepts image templates. Use `/v1/pdf/create` for PDF templates.

**Credits:** 1 credit deducted per successful generation.

**Rate Limits:** 60 requests/min (free), 120 requests/min (paid). Headers included in response.

## Request body

- CreateImageRequest — Request model for image generation
  - `template_id` string, required — Template short ID (12 characters)
  - `modifications` Modification[], nullable — Modify template elements by their layer name (set in the editor's Layers panel). Each item targets a layer and can set its text, image, colors, or visibility. Unknown layer names are skipped and reported in the response `warnings`.
    - `name` string, required — Name of the layer to modify (set via the editor's Layers panel). Matched against the element's `data-layer-name`, falling back to its `id`.
    - `text` string, nullable — Replace the element's text content. Rendered as literal text (HTML and `{{ }}` are not interpreted).
    - `image_url` string, nullable — Set the image source. For an `<img>` element this sets `src`; for any other element it sets a `background-image`.
    - `color` string, nullable — CSS color applied to the element's text (`color`).
    - `background` string, nullable — CSS color applied to the element's background (`background-color`).
    - `hidden` boolean, nullable — Hide (`true`) or show (`false`) the element.
  - `data` object — Optional key-value data merged into `{{ }}` template variables. For most image templates, prefer `modifications` instead.
  - `format` 'png' | 'jpeg' | 'webp' — Image output format options
  - `width` integer, nullable — Output width in pixels (height follows the template aspect ratio). Defaults to the template's native pixel width.
  - `quality` integer — Compression quality for `jpeg`/`webp` (1-100). Ignored for `png`.
  - `export_type` 'url' | 'binary' — Output delivery type options
  - `expiration` integer — URL expiration in seconds. Min: 60 (1 min), Max: 604800 (7 days). Only applies to `url` export type.
  - `filename` string, nullable — Custom filename (without extension). If not provided, defaults to 'document'. Only applies to `url` export type.
  - `store_s3` boolean — Upload to your configured S3 bucket instead of CDN
  - `s3_filepath` string, nullable — Custom path prefix in your S3 bucket. Uses default prefix if not provided.
  - `s3_bucket` string, nullable — Override the default bucket configured in your S3 integration.
  - `version` string, nullable — Optional version tag (e.g. `prod`) or version number (e.g. `3`). When omitted, uses the current draft.

## Response `200`

Image generated successfully

- CreateImageResponse — Response for URL export type
  - `url` string, required — Signed URL to download the image (expires after specified time)
  - `filename` string, required — Filename of the generated image
  - `credits_remaining` integer, required — Remaining credits after this request
  - `expires_in` integer, required — Seconds until the signed URL expires
  - `warnings` string[], nullable — Non-fatal warnings, e.g. modification layer names that matched no element.

## Other responses

- `400` — Template is not an image template, or has more than one page
- `402` — Insufficient credits
- `403` — Access denied - not your template
- `404` — Template not found
- `422` — Validation Error
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/pdftemplateapi/apis/templatefox-api.md) · [All operations](https://skmtc.net/pdftemplateapi/apis/templatefox-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pdftemplateapi/templatefox-api/revisions/5673fc0d5fad/schema)