Templates API

Templates are pre-designed video and banner layouts. Use these endpoints to list templates, get configurations, and create materials from templates.

Endpoints

Method Endpoint Description
GET /api/templates List all templates
GET /api/templates/families Get template families
GET /api/templates/{id}/configs Get template configuration
GET /api/templates/{id}/data Get template data
POST /api/templates/{id}/materials Create material from template
POST /api/templates/{id}/materials/v2 Create material (v2 batch)
POST /api/templates/{id}/preview Generate preview
GET /api/templates/{id}/assetbundles Get asset bundles

List Templates

GET /api/templates

Retrieve all available templates in your account.

Response

{
  "success": true,
  "data": [
    {
      "id": "tpl_social_v1",
      "name": "Social Media Video",
      "description": "Vertical video optimized for TikTok and Instagram",
      "category": "social",
      "formats": ["1080x1920", "1080x1080", "1920x1080"],
      "thumbnail": "https://cdn.adbot.fi/templates/tpl_social_v1.jpg",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "tpl_banner_v1",
      "name": "Display Banner",
      "description": "Standard IAB display ad sizes",
      "category": "display",
      "formats": ["300x250", "728x90", "160x600", "320x50"],
      "thumbnail": "https://cdn.adbot.fi/templates/tpl_banner_v1.jpg",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Template Families

GET /api/templates/families

Get templates grouped by family/category.

Response

{
  "success": true,
  "data": {
    "social": {
      "name": "Social Media",
      "templates": ["tpl_social_v1", "tpl_social_v2"]
    },
    "display": {
      "name": "Display Advertising",
      "templates": ["tpl_banner_v1", "tpl_banner_v2"]
    },
    "signage": {
      "name": "Digital Signage",
      "templates": ["tpl_signage_v1"]
    }
  }
}

Get Template Configuration

GET /api/templates/{templateId}/configs

Get the configuration and required fields for a template.

Response

{
  "success": true,
  "data": {
    "templateId": "tpl_social_v1",
    "name": "Social Media Video",
    "duration": 15,
    "fields": [
      {
        "name": "headline",
        "label": "Headline Text",
        "type": "text",
        "required": true,
        "maxLength": 50,
        "placeholder": "Enter your headline"
      },
      {
        "name": "subheadline",
        "label": "Subheadline",
        "type": "text",
        "required": false,
        "maxLength": 100
      },
      {
        "name": "productImage",
        "label": "Product Image",
        "type": "image",
        "required": true,
        "aspectRatio": "1:1",
        "minWidth": 500,
        "formats": ["jpg", "png", "webp"]
      },
      {
        "name": "backgroundColor",
        "label": "Background Color",
        "type": "color",
        "required": false,
        "default": "#ffffff"
      },
      {
        "name": "ctaText",
        "label": "Call to Action",
        "type": "text",
        "required": false,
        "default": "Shop Now",
        "maxLength": 20
      }
    ],
    "outputs": [
      {
        "format": "1080x1920",
        "name": "Vertical (9:16)",
        "platforms": ["TikTok", "Instagram Reels", "YouTube Shorts"]
      },
      {
        "format": "1080x1080",
        "name": "Square (1:1)",
        "platforms": ["Instagram Feed", "Facebook"]
      },
      {
        "format": "1920x1080",
        "name": "Horizontal (16:9)",
        "platforms": ["YouTube", "LinkedIn"]
      }
    ]
  }
}

Get Template Data

GET /api/templates/{templateId}/data

Get the full template data structure including animations and layers.

Create Material from Template

POST /api/templates/{templateId}/materials

Create a new material (video/banner) from a template.

Request Body

{
  "name": "Summer Campaign Video",
  "data": {
    "headline": "Summer Sale - 50% Off!",
    "subheadline": "Limited time offer",
    "productImage": "https://example.com/images/product.png",
    "backgroundColor": "#f5f5f5",
    "ctaText": "Shop Now"
  },
  "outputs": ["1080x1920", "1080x1080"]
}

Response

{
  "success": true,
  "data": {
    "id": "mat_xyz789",
    "name": "Summer Campaign Video",
    "templateId": "tpl_social_v1",
    "status": "processing",
    "outputs": ["1080x1920", "1080x1080"],
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Note: Video generation is asynchronous. Poll the material status or use webhooks to know when it's ready.

Create Material (v2)

POST /api/templates/{templateId}/materials/v2

Enhanced material creation with additional options like batch processing and callbacks.

Request Body

{
  "materials": [
    {
      "name": "Product A Video",
      "data": {
        "headline": "Product A - 30% Off",
        "productImage": "https://example.com/product-a.png"
      }
    },
    {
      "name": "Product B Video",
      "data": {
        "headline": "Product B - 40% Off",
        "productImage": "https://example.com/product-b.png"
      }
    }
  ],
  "outputs": ["1080x1920"],
  "callback": {
    "url": "https://your-server.com/webhook",
    "events": ["completed", "failed"]
  }
}

Generate Preview

POST /api/templates/{id}/preview

Generate a quick preview image of a template with custom data.

Request Body

{
  "data": {
    "headline": "Preview Text",
    "productImage": "https://example.com/product.png"
  },
  "format": "1080x1920"
}

Response

{
  "success": true,
  "data": {
    "previewUrl": "https://cdn.adbot.fi/previews/prev_abc123.jpg",
    "expiresAt": "2024-01-15T11:30:00Z"
  }
}

Get Asset Bundles

GET /api/templates/{templateId}/assetbundles

Get available asset bundles (fonts, icons, graphics) for a template.

Response

{
  "success": true,
  "data": {
    "bundles": [
      {
        "id": "bundle_fonts",
        "name": "Brand Fonts",
        "assets": [
          { "name": "Montserrat Bold", "type": "font" },
          { "name": "Open Sans", "type": "font" }
        ]
      },
      {
        "id": "bundle_icons",
        "name": "Social Icons",
        "assets": [
          { "name": "Instagram", "type": "icon" },
          { "name": "TikTok", "type": "icon" }
        ]
      }
    ]
  }
}