Text Rendering

Add text elements to your images with full control over typography, positioning, and styling.

Basic Text Properties

{
  "type": "image",
  "config": {
    "width": 600,
    "height": 300,
    "backgroundColor": "#f8f9fa",
    "layers": [
      {
        "type": "text",
        "text": "Basic Text",
        "x": 50,
        "y": 50,
        "fontSize": 28,
        "color": "#333333"
      },
      {
        "type": "text",
        "text": "Large Text",
        "x": 50,
        "y": 100,
        "fontSize": 48,
        "color": "#007acc"
      },
      {
        "type": "text",
        "text": "Text with Background",
        "x": 50,
        "y": 170,
        "fontSize": 24,
        "color": "#ffffff",
        "backgroundColor": "#ff6b6b"
      },
      {
        "type": "text",
        "text": "Centered Text",
        "x": 300,
        "y": 50,
        "fontSize": 24,
        "color": "#4ecdc4",
        "align": "center"
      },
      {
        "type": "text",
        "text": "Right Aligned",
        "x": 580,
        "y": 100,
        "fontSize": 20,
        "color": "#45b7d1",
        "align": "right"
      },
      {
        "type": "text",
        "text": "Small Text",
        "x": 50,
        "y": 220,
        "fontSize": 16,
        "color": "#666666"
      },
      {
        "type": "text",
        "text": "Colored Text",
        "x": 50,
        "y": 250,
        "fontSize": 22,
        "color": "#e74c3c"
      },
      {
        "type": "text",
        "text": "Semi-Transparent",
        "x": 300,
        "y": 170,
        "fontSize": 24,
        "color": "#2c3e50",
        "opacity": 0.6
      }
    ]
  }
}

Essential Properties

Property	Type	Required	Description
text	string	✅	Text content to display
x, y	number	❌	Position in pixels
position	string / Object	❌	Position by name or advanced positioning
fontSize	number	❌	Font size in pixels (default: 24)
color	string	❌	Text color (default: "#000000")
align	string	❌	Text alignment: left, center, right
backgroundColor	string	❌	Background color for text (single line only)
fontPath	string	❌	Path to custom font file
wrap	boolean	❌	Enable text wrapping
lineHeight	number	❌	Line height multiplier (e.g., 1.4)

Default Font

JsonCut uses Arial as the default font. For other fonts, you need to upload custom font files:

Custom Fonts

Upload your own font files for unique typography:

{
  "type": "image",
  "config": {
    "width": 600,
    "height": 200,
    "backgroundColor": "#f8f9fa",
    "layers": [
      {
        "type": "text",
        "text": "Custom Font",
        "x": 300, "y": 0,
        "fontSize": 36,
        "fontPath": "/font/2000-09-10/cmejszvz/10c8dfe0-c290-452a-bd31-0650b04f3b17.ttf",
        "color": "#007acc",
        "align": "center"
      },
      {
        "type": "text",
        "text": "Another Custom Font",
        "x": 300, "y": 70,
        "fontSize": 30,
        "fontPath": "/font/2000-09-10/cmejszvz/69333f97-7d77-4953-a43d-7ae59cb0cc1e.ttf",
        "color": "#007acc",
        "align": "center"
      },
      {
        "type": "text",
        "text": "Another Custom Font 2",
        "x": 300, "y": 110,
        "fontSize": 24,
        "fontPath": "/font/2000-09-10/cmejszvz/59fd6b7d-ae67-4191-adf0-c89eab710a49.ttf",
        "color": "#007acc",
        "align": "center"
      },
      {
        "type": "text",
        "text": "Default Font",
        "x": 300, "y": 150,
        "fontSize": 20,
        "color": "#007acc",
        "align": "center"
      }
    ]
  }
}

Font Upload Process

1. Upload your font file via the Files API with category="font"
2. Use the returned storageUrl as the fontPath property
3. Supported formats: .ttf, .otf, .woff, .woff2

curl -L 'https://api.jsoncut.com/v1/files/upload' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'file=@"/path/to/font.ttf"' \
-F 'category="font"'

For more details, see API reference

Text Alignment

Control horizontal text alignment:

{
  "type": "image",
  "config": {
    "width": 600,
    "height": 200,
    "backgroundColor": "#ffffff",
    "layers": [
      {
        "type": "text", "text": "Left Aligned",
        "x": 300, "y": 50, "fontSize": 24, "align": "left", "color": "#ff6b6b"
      },
      {
        "type": "text", "text": "Center Aligned",
        "x": 300, "y": 100, "fontSize": 24, "align": "center", "color": "#4ecdc4"
      },
      {
        "type": "text", "text": "Right Aligned", 
        "x": 300, "y": 150, "fontSize": 24, "align": "right", "color": "#45b7d1"
      }
    ]
  }
}

Alignment Options

• left: Align to the left edge (default)
• center: Center horizontally at the x position
• right: Align to the right edge at the x position

Font Sizes and Colors

{
  "type": "image",
  "config": {
    "width": 600,
    "height": 300,
    "backgroundColor": "#ffffff",
    "layers": [
      {
        "type": "text", "text": "Large Headline (48px)",
        "x": 50, "y": 50, "fontSize": 48, "color": "#333333"
      },
      {
        "type": "text", "text": "Medium Title (32px)",
        "x": 50, "y": 110, "fontSize": 32, "color": "#555555"
      },
      {
        "type": "text", "text": "Body Text (24px)",
        "x": 50, "y": 160, "fontSize": 24, "color": "#666666"
      },
      {
        "type": "text", "text": "Small Caption (18px)",
        "x": 50, "y": 200, "fontSize": 18, "color": "#999999"
      },
      {
        "type": "text", "text": "Accent Color",
        "x": 50, "y": 240, "fontSize": 24, "color": "#007acc"
      }
    ]
  }
}

Text Wrapping

Enable automatic text wrapping for longer content:

{
  "type": "image",
  "config": {
    "width": 600,
    "height": 400,
    "backgroundColor": "#ffffff",
    "layers": [
      {
        "type": "text",
        "text": "This is a longer text that automatically wraps to multiple lines when the wrap property is enabled. It demonstrates left alignment for better readability.",
        "x": 50, "y": 20,
        "width": 400,
        "fontSize": 18,
        "color": "#333333",
        "wrap": true,
        "lineHeight": 1.4,
        "align": "left"
      },
      {
        "type": "text",
        "text": "This text demonstrates center alignment with wrapping. The text will wrap to multiple lines while staying centered within the specified width boundaries.",
        "x": 300, "y": 130,
        "width": 500,
        "fontSize": 18,
        "color": "#007acc",
        "wrap": true,
        "lineHeight": 1.4,
        "align": "center"
      },
      {
        "type": "text",
        "text": "This example shows right-aligned text with wrapping enabled. Each line will be aligned to the right edge while maintaining proper line spacing and readability.",
        "x": 550, "y": 240,
        "width": 350,
        "fontSize": 18,
        "color": "#ff6b6b",
        "wrap": true,
        "lineHeight": 1.4,
        "align": "right"
      }
    ]
  }
}

Text Wrapping Properties

• wrap: Set to true to enable text wrapping
• width: Required when using wrap - defines the wrap boundary
• lineHeight: Controls spacing between lines (e.g., 1.4 = 140% of font size)

Manual Line Breaks

You can also force line breaks manually using \n in your text:

{
  "type": "text",
  "text": "First line\nSecond line\nThird line",
  "x": 50, "y": 50,
  "fontSize": 20,
  "color": "#333333"
}

This works with or without the wrap property enabled.

Text Effects

Apply visual effects to text layers:

{
  "type": "image",
  "config": {
    "width": 600,
    "height": 300,
    "backgroundColor": "#f0f0f0",
    "layers": [
      {
        "type": "text", "text": "Normal Text",
        "x": 50, "y": 50, "fontSize": 28, "color": "#333333"
      },
      {
        "type": "text", "text": "Semi-Transparent",
        "x": 50, "y": 100, "fontSize": 28, "color": "#007acc",
        "opacity": 0.6
      },
      {
        "type": "text", "text": "Rotated Text",
        "x": 50, "y": 150, "fontSize": 28, "color": "#ff6b6b",
        "rotation": 15
      },
      {
        "type": "text", "text": "Blurred Text",
        "x": 50, "y": 200, "fontSize": 28, "color": "#4ecdc4",
        "blur": 2
      }
    ]
  }
}

Available Effects

• opacity: Control transparency (0.0 to 1.0)
• rotation: Rotate text in degrees
• blur: Apply blur effect in pixels

Positioning Text

Text can be positioned using coordinates or position strings:

{
  "type": "image",
  "config": {
    "width": 600,
    "height": 200,
    "backgroundColor": "#ffffff",
    "layers": [
      {
        "type": "text", "text": "Pixel Position",
        "x": 50, "y": 50, "fontSize": 20, "color": "#333333"
      },
      {
        "type": "text", "text": "String Position",
        "position": "center", "align": "center",
        "fontSize": 20, "color": "#007acc"
      },
      {
        "type": "text", "text": "Relative Position",
        "position": { "x": 0.8, "y": 0.8, "originX": "right", "originY": "bottom" },
        "fontSize": 20, "color": "#ff6b6b"
      }
    ]
  }
}

Common Issues

Text not visible:

• Check color contrast against background
• Verify coordinates are within canvas bounds

Font not loading:

• Confirm font file was uploaded with category="font"
• Check fontPath matches the upload response storageUrl

Text wrapping problems:

• Set width property when using wrap: true
• Adjust lineHeight for better spacing