Documentation

Learn how to generate dynamic images using our API

API Reference

Complete OpenAPI specification with all endpoints

View the auto-generated OpenAPI documentation for detailed endpoint specifications, request/response schemas, and authentication details.

Quickstart Guide

1. Create Your First Template

Navigate to Templates → New Template

Choose a preset (e.g., OG Image 1200×630px)

Add layers with semantic names: title, subtitle, logo

Save the template and note your Template ID

2. Create an API Key

Go to App → API Keys → Create New Key to generate your authentication token

3. Generate via API (Authenticated)

Use layer overrides to dynamically customize your template:

const response = await fetch('https://yourdomain.com/api/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    templateId: 'your-template-id',
    layers: {
      title: { text: 'My Blog Post Title' },
      subtitle: {
        text: 'Published on Jan 15',
        fontSize: 24,
        color: '#666666'
      },
      logo: {
        image_url: 'https://example.com/logo.png',
        width: 120,
        height: 120
      }
    },
    format: 'png' // or 'jpeg', 'webp'
  })
});

const { success, imageUrl, cached } = await response.json();
// Use imageUrl in your application

4. Generate via URL (Public, No Auth)

For public templates, generate images directly via URL with JSON-encoded layer data:

# Simple text override
/api/render?templateId=uuid&layers={"title":{"text":"Hello World"}}

# Multiple layer overrides
/api/render?templateId=uuid&layers={"title":{"text":"Blog Title"},"subtitle":{"text":"By John Doe"},"logo":{"image_url":"https://example.com/avatar.jpg"}}

# Use in HTML
<meta property="og:image" content="https://yourdomain.com/api/render?templateId=..." />

Note: The public endpoint doesn't require authentication and doesn't count toward rate limits. Perfect for social media OG images!

5. Edit Templates Programmatically (Optional)

Update existing templates via API for programmatic template management, bulk updates, or CI/CD integration:

const response = await fetch('https://yourdomain.com/api/templates/your-template-id', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Updated Template Name',
    description: 'Updated description',
    jsonData: {
      canvas: { width: 1200, height: 630, background: '#ffffff' },
      layers: [
        // Your updated layer definitions
      ],
      variables: []
    }
  })
});

const updatedTemplate = await response.json();

Updatable fields: name, description, jsonData, previewUrl

Template Creation Guide

Layer Naming (Critical Concept)

• Each layer needs a unique name (e.g., "title", "avatar", "date")
• Layer names are used as keys in the API
• Choose semantic names that describe the content
• Use lowercase with underscores (e.g., "post_title", "author_avatar")

Layer Types & Overrides

Text Layers

Override text content and styling:

{
  "title": {
    "text": "New content",
    "fontSize": 48,
    "fontWeight": "bold",
    "color": "#000000",
    "textAlign": "center",
    "lineHeight": 1.2,
    "letterSpacing": -1,
    "textTransform": "uppercase"
  }
}

Image Layers

Override image source and display properties:

{
  "avatar": {
    "image_url": "https://example.com/avatar.jpg",
    "width": 120,
    "height": 120,
    "objectFit": "cover",
    "borderRadius": 60,
    "opacity": 1
  }
}

Canvas Setup

Common Presets

OG Image: 1200×630px
Twitter Card: 1200×600px
Instagram Post: 1080×1080px
Instagram Story: 1080×1920px

Best Practices

Keep important content 50px from edges
Use solid backgrounds for better readability
Limit title text to 60 characters max
Test with realistic content

Typography Guidelines

Recommended Font Sizes

Main title: 64-96px
Subtitle: 32-48px
Body text: 24-32px
Small text: 18-24px

Font Weights

Titles: Bold (700+)
Body: Regular/Medium (400-500)
Contrast: Ensure WCAG AA minimum

Testing Your Template

• Use the preview panel in the editor with sample data
• Test with realistic content (long titles, short titles, edge cases)
• Try different layer override combinations
• Check rendering at actual size (not zoomed)

Rate Limits & Usage

Rate limits are based on your subscription plan and reset monthly:

• Free Plan: 100 generations/month
• Starter Plan: 1,000 generations/month
• Pro Plan: 5,000 generations/month
• Business Plan: Unlimited generations

Note: Cached responses don't count toward your limit. The public /api/render endpoint also doesn't count toward rate limits.

Need Help?

Questions about the API or template creation? Contact our support team