Back to Documentation

API Documentation

Generate images and PDFs programmatically using our REST API

Table of Contents

Authentication

All API requests require authentication using an API key. You can create and manage your API keys in your account dashboard .

Authentication Methods

You can authenticate in two ways:

1. Using X-API-Key Header

X-API-Key: your_api_key_here

2. Using Authorization Bearer Token 

Authorization: Bearer your_api_key_here

Endpoints

Templates On provides two main endpoints for generating images and PDFs from templates.

POST/GET /api/v1/image

Generate PNG images from templates or simple text parameters.

Endpoint

https://your-domain.com/api/v1/image

Usage Modes

1. Template Mode

Use a saved template and optionally override its parameters.

Parameters

  • templateId (required) - UUID of the template
  • [paramName] (optional) - Any template parameter to override

Example (cURL)

curl -X POST https://your-domain.com/api/v1/image \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "title": "Software Engineer"
  }' \
  --output image.png

Example (JavaScript)

const response = await fetch('https://your-domain.com/api/v1/image', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: '123e4567-e89b-12d3-a456-426614174000',
    name: 'John Doe',
    title: 'Software Engineer',
  }),
});

const blob = await response.blob();
const url = URL.createObjectURL(blob);
// Use the image URL

2. Query Parameter Mode

Generate simple text images without creating a template.

Parameters

  • content (optional) - Text content (default: "Hello World")
  • width (optional) - Image width in pixels (default: 800, max: 4096)
  • height (optional) - Image height in pixels (default: 600, max: 4096)
  • fontSize (optional) - Font size (default: 32, min: 8, max: 400)
  • fontWeight (optional) - Font weight (default: 400)
  • color (optional) - Text color hex (default: "#000000")
  • backgroundColor (optional) - Background color hex (default: "#ffffff")
  • textAlign (optional) - Text alignment: left, center, right (default: "center")
  • padding (optional) - Padding in pixels (default: 40)

Example (GET Request)

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

Example (POST Request)

const response = await fetch('https://your-domain.com/api/v1/image', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: 'Hello World',
    width: 1200,
    height: 630,
    fontSize: 48,
    color: '#ffffff',
    backgroundColor: '#000000',
  }),
});

const blob = await response.blob();

Response

Returns a PNG image file with Content-Type: image/png

  • Maximum file size: 10MB
  • Cache-Control: public, max-age=3600

POST/GET /api/v1/pdf

Generate PDF documents from templates or simple text parameters.

Endpoint

https://your-domain.com/api/v1/pdf

The PDF endpoint works identically to the Image endpoint, with the same parameters and modes. The only difference is that it returns a PDF file instead of a PNG image.

Example (Template Mode)

curl -X POST https://your-domain.com/api/v1/pdf \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe"
  }' \
  --output document.pdf

Example (Query Parameter Mode)

curl "https://your-domain.com/api/v1/pdf?content=Hello%20PDF&width=800&height=600" \
  -H "X-API-Key: your_api_key_here" \
  --output document.pdf

Response

Returns a PDF file with Content-Type: application/pdf

  • Maximum file size: 10MB
  • Cache-Control: public, max-age=3600
  • Content-Disposition: inline; filename="template.pdf"

Error Handling

The API returns standard HTTP status codes and JSON error responses.

Error Response Format

{
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Validation failed: content: Content is required"
}

Common Error Codes

400 Bad Request

Invalid parameters or validation errors. Check your request parameters.

401 Unauthorized

Invalid or missing API key. Provide a valid API key via X-API-Key header or Authorization Bearer token.

403 Forbidden

Template access denied. The template is private and belongs to another user.

404 Not Found

Template does not exist. Check the template ID and try again.

413 Payload Too Large

Generated file exceeds 10MB limit. Reduce dimensions or complexity.

429 Too Many Requests

Rate limit exceeded. Upgrade your plan or wait for the limit to reset.

500 Internal Server Error

Server error during generation. Contact support if the issue persists.

504 Gateway Timeout

Request timed out after 30 seconds. Try reducing dimensions or complexity.

Rate Limits

API rate limits are enforced based on your subscription plan. When you exceed your limit, you'll receive a 429 error response.

Rate Limit Headers

Check these response headers to monitor your usage:

  • X-RateLimit-Limit - Your total rate limit
  • X-RateLimit-Remaining - Remaining requests
  • X-RateLimit-Reset - When the limit resets

To increase your rate limits, upgrade your subscription plan in your account settings .

Need Help?

If you have questions or need assistance with the API, feel free to reach out: