Image Generator API v2.0.0

✨ What's New in v2.0.0

Configurable Text Shadow: Enable/disable, custom colors (black, transparent, any CSS color), blur, and offset control
Custom Gradient Backgrounds: Define your own gradient colors with start/end parameters
Font Family Support: Choose from 8 font families (Arial, Helvetica, Times, Courier, Georgia, Verdana, Impact, Comic Sans)
Per-Item Configuration: Each text item can have its own shadow and font settings

📡 API Endpoints

GET /health

Health check endpoint - returns service status

POST /generate

Generate an image with text overlay(s)

📋 Parameters

Parameter	Type	Required	Default	Description
`imageData`	string	Optional	-	Base64 encoded image data (with or without data URI prefix)
`imageUrl`	string	Optional	-	HTTP(S) URL to background image
`textItems`	array	Optional	[]	Array of text objects with position, content, and styling
`text`	string	Optional	-	Single text string (legacy mode - centered)
`width`	number	Optional	1080	Canvas width in pixels
`height`	number	Optional	1080	Canvas height in pixels
`fontSize`	number	Optional	60	Default font size (legacy mode)
`fontColor`	string	Optional	white	Default font color (legacy mode)
`fontFamily` NEW	string	Optional	arial	Default font family: arial, helvetica, times, courier, georgia, verdana, impact, comic-sans
`textShadow` NEW	bool/object	Optional	true	Text shadow config: true, false, or {color, blur, offsetX, offsetY}
`gradientColors` NEW	object	Optional	{start:'#5b2c87',end:'#66cc00'}	Gradient background colors: {start, end}

Text Item Object Structure (v2.0.0)

        {
  "text": "Your text here",
  "position": "top-right",
  "fontSize": 40,
  "fontColor": "white",
  "fontFamily": "arial",
  "maxWidth": 900,
  "textShadow": {
    "color": "rgba(0,0,0,0.8)",
    "blur": 20,
    "offsetX": 3,
    "offsetY": 3
  }
}
      

Available Positions: top-left, top-center, top-right, middle-left, middle-center, middle-right, bottom-left, bottom-center, bottom-right

Text Shadow Options:

true - Default shadow (black, blur 20, offset 3x3)
false - No shadow
{color: "black"} - Solid black shadow with default blur/offset
{color: "transparent"} - No shadow
{color: "rgba(255,0,0,0.5)", blur: 10, offsetX: 2, offsetY: 2} - Custom shadow

🔧 Example Requests

1. Custom Gradient with No Text Shadow

curl -X POST https://images.kwatateam.com/generate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Clean Text, No Shadow",
    "width": 1200,
    "height": 630,
    "fontSize": 80,
    "fontColor": "#ffffff",
    "fontFamily": "impact",
    "textShadow": false,
    "gradientColors": {
      "start": "#ff6b6b",
      "end": "#4ecdc4"
    }
  }' \
  --output no_shadow.png

2. Multiple Text Items with Different Shadows

curl -X POST https://images.kwatateam.com/generate \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/background.jpg",
    "textItems": [
      {
        "text": "No Shadow Header",
        "position": "top-center",
        "fontSize": 48,
        "fontColor": "#ffffff",
        "fontFamily": "helvetica",
        "textShadow": false
      },
      {
        "text": "Black Shadow Quote",
        "position": "middle-center",
        "fontSize": 72,
        "fontColor": "#66cc00",
        "fontFamily": "georgia",
        "maxWidth": 900,
        "textShadow": {
          "color": "black",
          "blur": 15,
          "offsetX": 4,
          "offsetY": 4
        }
      },
      {
        "text": "Transparent Shadow Footer",
        "position": "bottom-center",
        "fontSize": 36,
        "fontColor": "#ffffff",
        "fontFamily": "courier",
        "textShadow": {
          "color": "transparent"
        }
      }
    ]
  }' \
  --output mixed_shadows.png

3. Custom Gradient with Font Families

curl -X POST https://images.kwatateam.com/generate \
  -H "Content-Type: application/json" \
  -d '{
    "gradientColors": {
      "start": "#667eea",
      "end": "#764ba2"
    },
    "textItems": [
      {
        "text": "Impact Font",
        "position": "top-center",
        "fontSize": 56,
        "fontColor": "white",
        "fontFamily": "impact"
      },
      {
        "text": "Georgia Serif",
        "position": "middle-center",
        "fontSize": 64,
        "fontColor": "#ffd700",
        "fontFamily": "georgia"
      },
      {
        "text": "Comic Sans Fun",
        "position": "bottom-center",
        "fontSize": 48,
        "fontColor": "#ff69b4",
        "fontFamily": "comic-sans"
      }
    ]
  }' \
  --output font_showcase.png

4. n8n Integration with v2.0 Features

// In n8n HTTP Request node:
// Method: POST
// URL: https://images.kwatateam.com/generate
// Body Content Type: JSON
// Response Format: File

{
  "imageData": "{{ $binary.data.data }}",
  "gradientColors": {
    "start": "#ff6b6b",
    "end": "#4ecdc4"
  },
  "textItems": [
    {
      "text": "{{ $now.format('MMMM DD, YYYY') }}",
      "position": "top-right",
      "fontSize": 32,
      "fontColor": "white",
      "fontFamily": "helvetica",
      "textShadow": false
    },
    {
      "text": "{{ $('quote_generator').item.json.quote }}",
      "position": "middle-center",
      "fontSize": 72,
      "fontColor": "#66cc00",
      "fontFamily": "georgia",
      "maxWidth": 950,
      "textShadow": {
        "color": "rgba(0,0,0,0.9)",
        "blur": 25,
        "offsetX": 5,
        "offsetY": 5
      }
    },
    {
      "text": "Visit kwatainc.com",
      "position": "bottom-center",
      "fontSize": 40,
      "fontColor": "white",
      "fontFamily": "impact",
      "textShadow": true
    }
  ]
}

📤 Response

The API returns the generated image as a PNG file with Content-Type: image/png.

Success Response

Status Code: 200 OK
Content-Type: image/png
Body: Binary PNG image data

Error Response

        {
  "error": "Error description",
  "details": "Detailed error message"
}
      

💡 Tips & Best Practices

✅ Use textShadow: false for clean, modern text on solid backgrounds
✅ Use textShadow: {color: "black", blur: 20} for better visibility on photos
✅ Custom gradients: Pick complementary colors for professional look
✅ Font families: Impact/Arial for headers, Georgia/Times for quotes, Courier for code
✅ Per-item shadow: Mix shadowed and non-shadowed text for visual hierarchy
⚠️ Transparent shadow = no shadow (same as false)
⚠️ Maximum request size: 50MB