REST API

API Reference

Generate images and PDFs programmatically. Manage templates, list available fields, and create AI-generated designs — all via HTTP.

REST / JSON

API Key Auth

Binary + JSON Responses

Base URLhttps://templateson.com/api/v1

Authentication

Every request must include a valid API key. Keys are created in your dashboard.

Method 1 — X-API-Key Header

The preferred method. Pass your key directly in the request header.

Method 2 — Bearer Token

Compatible with OAuth tooling and standard Authorization headers.

API keys are prefixed with son_key_ and are sensitive — treat them like passwords. Revoke and rotate if compromised.

http

POST /api/v1/image
X-API-Key: son_key_your_api_key_here

http

POST /api/v1/image
Authorization: Bearer son_key_your_api_key_here

Generation Endpoints

POSTGET/api/v1/image

Generate Image

Returns a PNG image. Supports two modes: Template Mode (use a saved template with optional parameter overrides) and Direct Mode (generate a styled text image on the fly without a template).

Returnsimage/png or application/json

Max size10 MB

Cache-Controlpublic, max-age=3600

Timeout30 s

Template Mode

Use a saved template and optionally override its parameters

Parameter

Type

Required

Description

templateId

string

required

UUID of the template to render

template_id

string

optional

Snake_case alias for templateId

[paramName]

string

optional

Any template dynamic field to override (flat or nested via params)

params

object

optional

Nested object of parameter overrides — preferred for Zapier/integrations

format

string

optional

Set to "json" to receive a base64-encoded JSON response instead of binary

curl

"token-function">curl -X POST https://templateson.com/api/v1/image \
  -H "X-API-Key: son_key_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "123e4567-e89b-12d3-a456-426614174000",
    "full_name": "Jane Smith",
    "job_title": "Product Designer"
  }' \
  --output card.png

Direct Mode

Generate styled text images without a template

Parameter

Type

Default

Constraints

content

string

"Hello World"

Max 10,000 chars

width

number

800

1 – 4096 px

height

number

600

1 – 4096 px

fontSize

number

32

8 – 400

fontWeight

number

400

100 – 900

color

string

"#000000"

Valid hex color

backgroundColor

string

"#ffffff"

Valid hex color

textAlign

string

"center"

left · center · right

padding

number

40

0 – 500 px

bash

curl "https://templateson.com/api/v1/image?content=Hello%20World&width=1200&height=630&fontSize=48&color=%23ffffff&backgroundColor=%23000000" \
  -H "X-API-Key: son_key_your_api_key_here" \
  --output image.png

JSON Response Mode — Add format=json or set Accept: application/json to receive a base64-encoded image in JSON. Useful for Zapier and no-code integrations.

{
  "success": true,
  "format": "png",
  "size": 48291,
  "data": "iVBORw0KGgoAAAANS...",
  "width": 1200,
  "height": 630
}

POSTGET/api/v1/pdf

Generate PDF

Identical parameters to /image. Returns a PDF file instead of a PNG. Supports both Template Mode and Direct Mode with the same parameter set.

Returnsapplication/pdf or application/json

Max size10 MB

Dispositioninline; filename="template.pdf"

Timeout30 s

The PDF endpoint accepts the exact same parameters as /image. Use templateId for template-based generation, or pass direct styling parameters for simple text documents.

When format=json is passed, returns a base64-encoded PDF in the same JSON envelope as the image endpoint.

bash

curl -X POST https://templateson.com/api/v1/pdf \
  -H "X-API-Key: son_key_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Jane Smith",
    "title": "Engineering Lead"
  }' \
  --output document.pdf

Template Endpoints

GET/api/v1/templates/list

List Templates

Returns all templates accessible to the authenticated API key — both public templates and templates owned by the key's account.

Authentication

Requires API key (X-API-Key or Bearer token).

Response

Returns a list of template summaries with id, name, and is_public status.

json response

{
  "templates": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "LinkedIn Banner",
      "is_public": false
    }
  ]
}

GET/api/v1/templates/:id/fields

Get Template Fields

Returns all dynamic fields (parameters) defined in a template. Use this to discover what parameter names to pass when generating images or PDFs.

URL Param

Type

Required

Description

:id

string

required

UUID of the template

Field types are text or image. Use the title value as the key when passing template parameters.

json response

{
  "template_id": "123e4567-...",
  "template_name": "LinkedIn Banner",
  "fields": [
    {
      "title": "full_name",
      "type": "text"
    },
    {
      "title": "profile_photo",
      "type": "image"
    }
  ]
}

POST/api/v1/templates/generate-with-agent

AI Template Generation

Generate a complete Fabric.js template design using AI. Pass a natural-language prompt and receive a fully structured template that is automatically saved to your account.

AuthAPI Key required

UsageCounts against AI quota

Parameter

Type

Required

Description

prompt

string

required

Natural language description of the design

name

string

required

Name for the saved template

width

number

optional

Canvas width in px (default: 1200)

height

number

optional

Canvas height in px (default: 630)

backgroundColor

string

optional

Background color hex (default: #ffffff)

mode

string

optional

"replace" (new design) or "edit" (modify existing). Default: "replace"

templateId

string

optional

Existing template UUID to overwrite (mode=replace only)

existingObjects

array

optional

Required when mode=edit — Fabric.js objects array to modify

is_public

boolean

optional

Whether the generated template is publicly accessible (default: false)

The returned template_id can be passed directly to /api/v1/image or /api/v1/pdf after opening the template once in the editor to generate its SVG.

bash

curl -X POST https://templateson.com/api/v1/templates/generate-with-agent \
  -H "X-API-Key: son_key_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A professional LinkedIn banner with a dark navy background, gold accent bar, name placeholder and job title",
    "name": "LinkedIn Banner",
    "width": 1584,
    "height": 396
  }'

json response

{
  "success": true,
  "template_id": "abc12345-...",
  "template_name": "LinkedIn Banner",
  "width": 1584,
  "height": 396,
  "json_content": { /* Fabric.js canvas JSON */ },
  "note": "svg_content is null until the template is opened in the dashboard editor."
}

API Key Endpoints

POST/api/v1/keys/validate

Validate API Key

Check whether an API key is valid and retrieve its metadata. Useful for onboarding flows or integration setup wizards.

Parameter

Type

Required

Description

key

string

optional

API key to validate (body). Alternatively use X-API-Key header.

json response

{
  "valid": true,
  "message": "API key is valid",
  "key_info": {
    "id": "key-uuid",
    "prefix": "son_key_abc",
    "label": "Production Key",
    "created_at": "2025-01-01T00:00:00Z",
    "last_used_at": "2025-04-15T10:30:00Z",
    "owner": {
      "id": "user-uuid",
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }
}

Reference

Error Handling

All errors return standard HTTP status codes with a JSON body describing the failure.

json error envelope

{
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Validation failed: width: Width must be between 1 and 4096"
}

400

Bad Request

Invalid parameters, malformed JSON body, or validation failure. Check the message field for specifics.

401

Unauthorized

Missing or invalid API key. Provide a valid key via X-API-Key header or Authorization Bearer token.

403

Forbidden

Template is private and belongs to another account. Use a public template or one your key owns.

404

Not Found

Template does not exist or the provided templateId is not a valid UUID.

413

Payload Too Large

Generated file exceeds 10 MB. Reduce canvas dimensions or design complexity.

429

Too Many Requests

Monthly or daily API request quota exceeded. Upgrade your plan or wait for the quota to reset.

500

Internal Server Error

Unexpected server error or rendering failure. Contact support if this persists.

503

Service Unavailable

Rendering service is temporarily unreachable. Retry in a moment.

504

Gateway Timeout

Rendering timed out after 30 seconds. Reduce image dimensions or complexity.

Rate Limits

Limits are enforced per subscription plan. Exceeding them returns a 429 response.

Response Headers

Monitor these headers to track consumption and avoid hitting limits.

X-RateLimit-LimitYour total request quota for the current period

X-RateLimit-RemainingRequests remaining before the limit is hit

X-RateLimit-ResetISO 8601 timestamp when the quota resets

Upgrade your plan in account settings to increase limits.

http response headers

HTTP/1.1 200 OK
Content-Type: image/png
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 2026-04-17T00:00:00Z

http 429 response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "statusCode": 429,
  "statusMessage": "Rate Limit Exceeded",
  "message": "You have exceeded your API usage limits."
}

Response Formats

Generation endpoints return binary files by default. Pass format=json or set Accept: application/json to switch to base64 JSON — useful for platforms that don't support binary responses (Zapier, Make, etc.).

Binary (Default)

Returns raw PNG or PDF binary. Set --output file.png in cURL or read the response as a Blob in JavaScript.

image/png · application/pdf

JSON + Base64

Returns { success, format, size, data, width, height } where data is base64-encoded. Ideal for no-code platforms.

application/json

Ready to build?

Generate your API key and start creating images and PDFs in minutes.

Get API Key Contact Support