API Documentation

Image Generation API

The Image Generation API allows you to programmatically create and customize images for various use cases. This RESTful API supports multiple output formats and offers different capabilities based on your subscription tier.

Base URL

https://craftr.art/api/v1/image

Authentication

All API requests require authentication using an API key. You must include your API key in the Authorization header as a Bearer token:

Authorization: Bearer your_api_key_here

To obtain an API key, sign up for an account on the Craftr.art Dashboard.

Rate Limits

Rate limits vary based on your subscription plan:

Plan	Monthly Request Limit	Component Limit per Image
Free	10 requests/month	10 components
Pro	1,000 requests/month	Unlimited

The API will return a 429 Too Many Requests response when you exceed your rate limit, along with a retryAfter timestamp indicating when you can make requests again.

Request Format

Endpoint: POST /api/v1/image

Headers:

• Authorization: Bearer your_api_key_here (required)
• Accept: Desired image format (optional, defaults to SVG)
  • Supported formats: image/svg+xml, image/png, image/jpeg, image/webp, image/tiff, image/avif
• Content-Type: application/json (required)

Request Body:

{
  "width": 1200,
  "height": 630,
  "background": "#ffffff",
  "components": [
    {
      "type": "text",
      "text": "Hello World",
      "fontSize": 48,
      "fontWeight": "700",
      "fontFamily": "Inter",
      "color": "#000000",
      "x": 600,
      "y": 315,
      "frameWidth": "fit"
    },
    {
      "type": "divider",
      "length": 1200,
      "width": "medium",
      "direction": "horizontal",
      "color": "#0070f3",
      "x": 0,
      "y": 0
    }
    // Additional components as needed
  ]
}

Component Types

The API supports the following component types that can be combined to create complex images:

Text Component

{
  "type": "text",
  "text": "Your text here",
  "fontSize": 32,
  "fontWeight": "700",
  "fontFamily": "Inter",
  "fontStyle": "normal",
  "color": "#000000",
  "x": 100,
  "y": 100,
  "frameWidth": "fit"
}

Property	Type	Possible Values	Description
text	string	Any text	The content to display
fontSize	number	Any positive number	Size of the font in pixels
fontWeight	string	"100", "200", "300", "400", "500", "600", "700", "800", "900"	Font weight (100=Thin, 400=Regular, 700=Bold)
fontFamily	string	"Inter", "Noto Sans", "Noto Sans SC", "Noto Sans TC", "Poppins", "Roboto", "Playfair Display"	Font family to use
fontStyle	string	"normal", "italic"	Style of the font
color	string	Hex color code	Text color
x	number	Any number	X-coordinate position
y	number	Any number	Y-coordinate position
frameWidth	string or number	"fit" or pixel width	Width of text frame ("fit" for auto)

Image Component

{
  "type": "image",
  "src": "https://example.com/image.png",
  "width": 300,
  "height": 200,
  "radius": 20,
  "x": 150,
  "y": 150
}

Property	Type	Possible Values	Description
src	string	URL or base64 data	Image source URL or base64-encoded image data
width	number	Any positive number	Width of the image in pixels
height	number	Any positive number	Height of the image in pixels
radius	number	Any positive number	Border radius in pixels for rounded corners
x	number	Any number	X-coordinate position
y	number	Any number	Y-coordinate position

Tag Component

{
  "type": "tag",
  "text": "Featured",
  "fontFamily": "Inter",
  "fontWeight": "600",
  "fontSize": 16,
  "color": "#ffffff",
  "backgroundColor": "#ff0000",
  "x": 50,
  "y": 50
}

Property	Type	Possible Values	Description
text	string	Any text	Tag text content
fontFamily	string	Same as text component	Font family for tag text
fontWeight	string	Same as text component	Font weight for tag text
fontSize	number	Any positive number	Size of the font in pixels
color	string	Hex color code	Text color
backgroundColor	string	Hex color code	Background color of the tag
x	number	Any number	X-coordinate position
y	number	Any number	Y-coordinate position

Divider Component

{
  "type": "divider",
  "length": 600,
  "width": "medium",
  "direction": "horizontal",
  "color": "#000000",
  "x": 300,
  "y": 400
}

Property	Type	Possible Values	Description
length	number	Any positive number	Length of the divider in pixels
width	string	"thin", "medium", "thick"	Thickness of the divider
direction	string	"horizontal", "vertical"	Orientation of the divider
color	string	Hex color code	Color of the divider
x	number	Any number	X-coordinate position
y	number	Any number	Y-coordinate position

Note for Free tier users: You are limited to a maximum of 10 components per image.

Response

The API will return the generated image in the requested format with the following headers:

Content-Type: image/[requested-format]
Content-Disposition: inline
Cache-Control: public, max-age=31536000

Error Responses

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Description
200	Success - image returned
400	Bad Request - invalid parameters
401	Unauthorized - missing or invalid Authorization header
403	Forbidden - invalid API key
429	Too Many Requests - rate limit exceeded
500	Internal Server Error

Error responses are returned in JSON format:

{
  "error": "Error description",
  "details": {} // Additional error details when available
}

For rate limit errors, the response includes a retryAfter timestamp:

{
  "error": "Rate limit exceeded",
  "retryAfter": "2023-12-01T00:00:00.000Z"
}

Examples

Basic Example: Generate an SVG image

const response = await fetch('https://craftr.art/api/v1/image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json',
    'Accept': 'image/svg+xml'
  },
  body: JSON.stringify({
    width: 1200,
    height: 630,
    background: '#ffffff',
    components: [
      {
        type: 'text',
        text: 'Hello World',
        fontSize: 48,
        fontWeight: '700',
        fontFamily: 'Inter',
        color: '#000000',
        x: 600,
        y: 315,
        frameWidth: 'fit'
      }
    ]
  })
});

// Handle the SVG response
if (response.ok) {
  const svgImage = await response.text();
  // Use the SVG data
}

Generate a PNG image

Simply change the Accept header to request a different format:

const response = await fetch('https://craftr.art/api/v1/image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json',
    'Accept': 'image/png'
  },
  // Same body as previous example
});

// Handle the PNG response
if (response.ok) {
  const pngBuffer = await response.arrayBuffer();
  // Use the PNG data
}

Best Practices

1. Cache Images: Images are served with a long cache duration. Consider caching images on your end to reduce API calls.
2. Request Only What You Need: Specify exactly the format you need via the Accept header to minimize conversion overhead.
3. Handle Rate Limits Gracefully: Implement exponential backoff for retries when rate limits are hit.
4. Component Efficiency: Keep your component count low, especially for free tier usage.

Support

For additional help or questions about the API, please contact support@craftr.art.