Visual content generation API for images and videos using templates and dynamic elements

Introduction

The Create API enables visual content generation including images and videos. It uses a template-based system with dynamic elements for positioning text, images, and other visual components.

Authentication

All API requests require authentication using an API key:

Authorization: Bearer your_api_key
# or
X-API-Key: your_api_key

Templates

GET /api/templates

List all available templates with pagination and filtering.

Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 20)
category_id	integer	Filter by category
type	string	image, video
search	string	Search by name

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Social Media Banner",
      "slug": "social-media-banner",
      "type": "image",
      "width": 1200,
      "height": 630,
      "preview_url": "/templates/1/preview.jpg",
      "category": {
        "id": 5,
        "name": "Social Media"
      },
      "element_count": 5,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45
  }
}

POST /api/templates

Create a new template.

Request Body

{
  "name": "Instagram Story",
  "type": "image",
  "width": 1080,
  "height": 1920,
  "category_id": 5,
  "background_color": "#ffffff",
  "background_image_url": "https://example.com/bg.jpg"
}

GET /api/templates/{id}

Get template details with all elements.

Response

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Social Media Banner",
    "type": "image",
    "width": 1200,
    "height": 630,
    "background_color": "#f5f5f5",
    "background_image_url": null,
    "elements": [
      {
        "id": 1,
        "type": "text",
        "name": "headline",
        "x": 50,
        "y": 100,
        "width": 500,
        "height": 80,
        "properties": {
          "font_family": "Arial",
          "font_size": 48,
          "font_weight": "bold",
          "color": "#333333",
          "text_align": "left"
        },
        "default_value": "Your Headline Here"
      },
      {
        "id": 2,
        "type": "image",
        "name": "product_image",
        "x": 600,
        "y": 50,
        "width": 500,
        "height": 500,
        "properties": {
          "fit": "cover",
          "border_radius": 10
        }
      }
    ]
  }
}

Elements

POST /api/templates/{template_id}/elements

Add an element to a template.

PUT /api/elements/{id}

Update an element's position, size, or properties.

Request Body

{
  "x": 100,
  "y": 150,
  "width": 600,
  "properties": {
    "font_size": 52,
    "color": "#000000"
  }
}

Content Generation

POST /api/generations

Generate an image or video from a template with dynamic values.

Request Body

{
  "template_id": 1,
  "values": {
    "headline": "Summer Sale - 50% Off!",
    "subtitle": "Limited time offer",
    "product_image": "https://example.com/product.jpg",
    "logo": "https://example.com/logo.png"
  },
  "output_format": "png",
  "quality": 90
}

Response

{
  "success": true,
  "data": {
    "id": "gen_abc123",
    "template_id": 1,
    "status": "completed",
    "output_url": "https://cdn.example.com/generations/gen_abc123.png",
    "width": 1200,
    "height": 630,
    "file_size": 245760,
    "created_at": "2024-01-22T14:30:00Z"
  }
}

GET /api/generations

List all generations with filtering options.

Parameters

Parameter	Type	Description
template_id	integer	Filter by template
status	string	pending, processing, completed, failed
from_date	date	Filter by date range

GET /api/generations/{id}

Get generation status and result.

Response

{
  "success": true,
  "data": {
    "id": "gen_abc123",
    "template_id": 1,
    "template_name": "Social Media Banner",
    "status": "completed",
    "values": {
      "headline": "Summer Sale - 50% Off!",
      "subtitle": "Limited time offer"
    },
    "output_url": "https://cdn.example.com/generations/gen_abc123.png",
    "output_format": "png",
    "width": 1200,
    "height": 630,
    "file_size": 245760,
    "render_time_ms": 1250,
    "created_at": "2024-01-22T14:30:00Z",
    "completed_at": "2024-01-22T14:30:01Z"
  }
}

Batch Generation

POST /api/generations/batch

Generate multiple images in a single request. Useful for creating variations or bulk content.

Request Body

{
  "template_id": 1,
  "items": [
    {
      "values": {
        "headline": "Product A - Now Available",
        "product_image": "https://example.com/product-a.jpg"
      }
    },
    {
      "values": {
        "headline": "Product B - 30% Off",
        "product_image": "https://example.com/product-b.jpg"
      }
    }
  ],
  "output_format": "png"
}

Response

{
  "success": true,
  "batch_id": "batch_xyz789",
  "total": 2,
  "status": "processing",
  "items": [
    {"id": "gen_001", "status": "pending"},
    {"id": "gen_002", "status": "pending"}
  ]
}

GET /api/generations/batch/{batch_id}

Get batch generation status and results.

Response

{
  "success": true,
  "batch_id": "batch_xyz789",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "failed": 0,
  "items": [
    {
      "id": "gen_001",
      "status": "completed",
      "output_url": "https://cdn.example.com/gen_001.png"
    },
    {
      "id": "gen_002",
      "status": "completed",
      "output_url": "https://cdn.example.com/gen_002.png"
    }
  ]
}

Assets

GET /api/assets

List uploaded assets (images, fonts, etc.).

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "company-logo.png",
      "type": "image",
      "mime_type": "image/png",
      "file_size": 15360,
      "url": "https://cdn.example.com/assets/company-logo.png",
      "width": 300,
      "height": 100,
      "created_at": "2024-01-10T10:00:00Z"
    }
  ]
}

POST /api/assets

Upload a new asset. Use multipart/form-data encoding.

Parameters

Field	Type	Description
file required	file	File to upload (max: 10MB)
name	string	Optional display name

Categories

GET /api/categories

List template categories.

Response

{
  "success": true,
  "data": [
    {"id": 1, "name": "Social Media", "slug": "social-media", "template_count": 25},
    {"id": 2, "name": "Email Headers", "slug": "email-headers", "template_count": 12},
    {"id": 3, "name": "Banners", "slug": "banners", "template_count": 18},
    {"id": 4, "name": "Thumbnails", "slug": "thumbnails", "template_count": 8}
  ]
}

POST /api/categories

Create a new category.

Request Body

{
  "name": "Product Cards",
  "description": "Templates for product showcase cards"
}

Error Codes

Code	Status	Description
TEMPLATE_NOT_FOUND	404	Template does not exist
INVALID_VALUES	400	Missing or invalid element values
RENDER_FAILED	500	Image/video rendering failed
FILE_TOO_LARGE	413	Uploaded file exceeds size limit
INVALID_FORMAT	400	Unsupported file format