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
googleFont	string	❌	Google Font (e.g., "roboto:600")
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

Alternative: Google Fonts

As an alternative to uploading fonts, you can use Google Fonts directly with the googleFont property:

{
  "type": "text",
  "text": "Google Font Example",
  "googleFont": "roboto:600",
  "fontSize": 36,
  "color": "#007acc"
}

Format: "fontFamily" or "fontFamily:weight" (e.g., "roboto" or "roboto:600")

Available weights: 100, 200, 300, 400 (regular), 500, 600, 700 (bold), 800, 900

Font naming: Use exact casing from Google Fonts (e.g., "Roboto" with capital R). If a font isn't found, try different casing variations.

Browse fonts at fonts.google.com. The font is automatically downloaded and cached.

note

You cannot use both googleFont and fontPath in the same layer.

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