v1

latestOpenAPI 3.1.02026-08-06244570.4 KB

Image

Generate image from template

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.

post/v1/image/create

Request body

template_idstring required

Template short ID (12 characters)

dataobject

Optional key-value data merged into {{ }} template variables. For most image templates, prefer modifications instead.

format'png' | 'jpeg' | 'webp'

Image output format options

widthinteger nullable

Output width in pixels (height follows the template aspect ratio). Defaults to the template's native pixel width.

qualityinteger

Compression quality for jpeg/webp (1-100). Ignored for png.

export_type'url' | 'binary'

Output delivery type options

expirationinteger

URL expiration in seconds. Min: 60 (1 min), Max: 604800 (7 days). Only applies to url export type.

filenamestring nullable

Custom filename (without extension). If not provided, defaults to 'document'. Only applies to url export type.

store_s3boolean

Upload to your configured S3 bucket instead of CDN

s3_filepathstring nullable

Custom path prefix in your S3 bucket. Uses default prefix if not provided.

s3_bucketstring nullable

Override the default bucket configured in your S3 integration.

versionstring nullable

Optional version tag (e.g. prod) or version number (e.g. 3). When omitted, uses the current draft.

Example request

{
  "export_type": "url",
  "format": "png",
  "modifications": [
    {
      "name": "title",
      "text": "Summer Sale -50%"
    },
    {
      "image_url": "https://example.com/photo.jpg",
      "name": "product_image"
    }
  ],
  "template_id": "HMQywVpZxqAM",
  "width": 1080
}

Response

Image generated successfully

urlstring required

Signed URL to download the image (expires after specified time)

filenamestring required

Filename of the generated image

credits_remaininginteger required

Remaining credits after this request

expires_ininteger required

Seconds until the signed URL expires

warningsstring[] nullable

Non-fatal warnings, e.g. modification layer names that matched no element.

Example response

{
  "credits_remaining": 99,
  "expires_in": 86400,
  "filename": "social-card.png",
  "url": "https://cdn.templatefox.com/generated/abc123/social-card.png"
}