API Reference

Complete specification for the Canvelete Render API.

Render Design

POST /render/design/{designId}

Generates an image from a design template with optional dynamic content.

Path Parameters

Parameter	Type	Required	Description
`designId`	string	Yes	Unique design identifier

Request Body

Field	Type	Required	Description
`format`	string	Yes	Output format: `png`, `jpg`, `webp`, `pdf`
`quality`	integer	No	Image quality (1-100). Default: 90
`width`	integer	No	Output width in pixels. Maintains aspect ratio if height not specified
`height`	integer	No	Output height in pixels. Maintains aspect ratio if width not specified
`scale`	number	No	Scale multiplier (0.1-5.0). Default: 1.0
`dynamicElements`	object	No	Element overrides (see below)
`cache`	boolean	No	Use cached render if available. Default: true
`webhook`	string	No	URL to receive completion notification

Dynamic Elements

Override text and image elements in the design:

{
  "dynamicElements": {
    "element_id": {
      "text": "Custom text content",
      "color": "#FF5733",
      "fontSize": 24,
      "fontWeight": "bold"
    },
    "image_element_id": {
      "src": "https://example.com/image.jpg",
      "fit": "cover"
    }
  }
}

Text Element Properties

Property	Type	Description
`text`	string	Text content
`color`	string	Hex color code
`fontSize`	integer	Font size in pixels
`fontWeight`	string	`normal`, `bold`, `light`
`fontStyle`	string	`normal`, `italic`

Image Element Properties

Property	Type	Description
`src`	string	Image URL (must be publicly accessible)
`fit`	string	`cover`, `contain`, `fill`, `scale-down`

Response

Success (200)

{
  "success": true,
  "data": {
    "imageUrl": "https://cdn.canvelete.com/renders/abc123.png",
    "format": "png",
    "width": 1920,
    "height": 1080,
    "fileSize": 245678,
    "renderTime": 1234,
    "cached": false
  }
}

Response Fields

Field	Type	Description
`imageUrl`	string	CDN URL of rendered image
`format`	string	Output format
`width`	integer	Image width in pixels
`height`	integer	Image height in pixels
`fileSize`	integer	File size in bytes
`renderTime`	integer	Render duration in milliseconds
`cached`	boolean	Whether result was served from cache

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Error Codes

Code	Status	Description
`INVALID_API_KEY`	401	Missing or invalid authentication
`INVALID_DESIGN_ID`	404	Design not found or inaccessible
`INVALID_FORMAT`	400	Unsupported output format
`INVALID_QUALITY`	400	Quality must be 1-100
`INVALID_DIMENSIONS`	400	Width/height out of bounds
`INVALID_ELEMENT_ID`	400	Element ID not found in design
`INVALID_IMAGE_URL`	400	Image URL inaccessible or invalid
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`RENDER_FAILED`	500	Internal rendering error
`WEBHOOK_FAILED`	500	Webhook delivery failed

Rate Limiting

Rate limit information is included in response headers:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1635724800

When rate limit is exceeded:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 3600 seconds.",
    "details": {
      "retryAfter": 3600
    }
  }
}

Webhooks

Receive notifications when renders complete (useful for long-running renders).

Webhook Request

POST to your specified webhook URL:

{
  "event": "render.completed",
  "timestamp": "2025-11-19T10:30:00Z",
  "data": {
    "designId": "abc123",
    "imageUrl": "https://cdn.canvelete.com/renders/xyz.png",
    "renderTime": 2345
  }
}

Webhook Headers

X-Canvelete-Signature: sha256=...
X-Canvelete-Event: render.completed

Verify webhook authenticity using HMAC signature with your API secret.

Example Requests

Basic Render

curl -X POST https://api.canvelete.com/api/v1/render/design/abc123 \
  -H "Authorization: Bearer cvt_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "png",
    "quality": 90
  }'

With Dynamic Content

curl -X POST https://api.canvelete.com/api/v1/render/design/abc123 \
  -H "Authorization: Bearer cvt_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "png",
    "quality": 95,
    "dynamicElements": {
      "headline": {
        "text": "Black Friday Sale",
        "color": "#FF0000"
      },
      "product_image": {
        "src": "https://example.com/product.jpg"
      }
    }
  }'

Custom Dimensions

curl -X POST https://api.canvelete.com/api/v1/render/design/abc123 \
  -H "Authorization: Bearer cvt_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "jpg",
    "width": 1200,
    "height": 630,
    "quality": 85
  }'

Overview Code Examples