Templates On
Start free
Docs
REST API Reference
v1
REST API

API Reference

Generate images and PDFs programmatically. Manage templates and list available fields, all via HTTP.

Nimo working with API code
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, so 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
01
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
02
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"
    }
  ]
}
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"
    }
  }
}
Webhooks
POST/api/v1/render/async

Async Render + Webhook

Submit a render job and have the result delivered to a URL you control. Accepts any normal /image, /pdf, or bulk body, plus a webhook_url. The response returns a job_id you can use to poll GET /api/v1/render/jobs/:id. When the render finishes, we POST the result to your webhook_url, signed so you can verify it came from us.

Parameter
Type
Required
Description
templateId
string
required
The template to render.
webhook_url
string
optional
HTTPS URL we POST the result to on completion.
format
string
optional
image (default) or pdf.
records
array
optional
One param object per output for a bulk job.
json response
{
  "job_id": "job-uuid",
  "status": "completed"
}
webhook payload (POST to your url)
{
  "job_id": "job-uuid",
  "status": "completed",
  "files": [{ "url": "https://.../0.png" }]
}

Verifying Webhook Signatures

Every webhook delivery (and every webhook render destination) includes an X-Webhook-Signature header: an HMAC-SHA256 of the raw request body, hex-encoded, keyed with your API key’s webhook signing secret. Find that secret on your API keys page — it’s shown next to each key. Recompute the HMAC on your end and compare; if it matches, the request genuinely came from us. The secret is never sent in the request, so guard it like a password.

node — verify a delivery
import { createHmac } from 'node:crypto'

// rawBody = the exact bytes you received (do NOT re-stringify a parsed object)
function isValid(rawBody, signatureHeader, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex')
  return expected === signatureHeader.trim().toLowerCase()
}
Verify against the raw body. The signature is computed over the exact byte string we send. If your framework parses JSON before you can read it, configure it to expose the raw body for this route, or the signature will never match.
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