Documentation
Complete reference for DrawByURL syntax and features
Quick Start
DrawByURL uses a packed key-value syntax where each element is described in a URL path segment. Elements are separated by forward slashes (/), and attributes within each element are separated by hyphens (-).
/{type}[-{key}-{value}]*[/{type2}[-{key}-{value}]*]*Each segment starts with an element type (circle, square, text, background, etc.), followed by any number of key-value pairs. The order of attributes doesn't matter—circle-color-blue-size-150 is the same as circle-size-150-color-blue.
Example:
/circle-color-blue-size-150Key Points:
- First token in each segment is the element type
- Remaining tokens are parsed as key-value pairs
- Use / to separate multiple elements
- Use - to separate attributes within an element
- Order of attributes doesn't matter
- Use short aliases (c, s, w, h, etc.) for cleaner URLs
- Use | in text-value for line breaks
- Use p suffix for relative positioning (e.g., x-50p) or decimals (x-0.5). For % in URLs, encode as %25.
✨ New Features:
- Human-readable aliases: Use
cinstead ofcolor,sinstead ofsize - New shapes: ellipse, polygon, heart, diamond, hexagon, octagon, arrow
- Groups & layouts: Use
group-layout-roworscene-layout-gridfor automatic arrangements - Shadows: Add
shadow-mediumor custom shadows - Rounded corners: Use
br-20for border radius - Multiline text: Use
|in text-value for line breaks - Smart defaults: Objects auto-position if no coordinates specified
Shapes Reference
DrawByURL supports 14+ shapes including circles, squares, polygons, hearts, diamonds, and more. Each shape can be customized with colors, sizes, positions, strokes, rotations, shadows, and more. Shapes are drawn in the order they appear in the URL, with later shapes appearing on top. Use human-readable aliases like c for color,s for size, w for width, and h for height to make URLs shorter and more readable.
circle
Creates a perfect circle
Example:
/circleSupported Attributes:
colorsizexystrokestroke-coloropacityrotatezshadowsquare
Creates a square shape
Example:
/square-c-blue-s-300Supported Attributes:
colorsizewidthheightxystrokestroke-coloropacityrotatefillzradiusshadowrectangle
Creates a rectangle with customizable width and height
Example:
/rectangle-c-green-w-500-h-250Supported Attributes:
colorwidthheightxystrokestroke-coloropacityrotatefillzradiusshadowtriangle
Creates a triangle shape
Example:
/triangle-c-purple-s-300Supported Attributes:
colorsizewidthheightxystrokestroke-coloropacityrotatefillzshadowstar
Creates a star (default 5 points, customizable)
Example:
/star-c-yellow-s-300Supported Attributes:
colorsizexystrokestroke-coloropacityrotatezpointsshadowellipse
Creates an ellipse (oval)
Example:
/ellipse-c-blue-w-500-h-250Supported Attributes:
colorwidthheightxystrokestroke-coloropacityrotatefillzshadowpolygon
Creates a polygon with customizable number of sides
Example:
/polygon-c-blue-s-250-pts-8Supported Attributes:
colorsizexystrokestroke-coloropacityrotatezpointsshadowheart
Creates a heart shape
Example:
/heart-c-red-s-250Supported Attributes:
colorsizexystrokestroke-coloropacityrotatezshadowdiamond
Creates a diamond shape
Example:
/diamond-c-green-w-250-h-200Supported Attributes:
colorwidthheightxystrokestroke-coloropacityrotatefillzshadowhexagon
Creates a hexagon (6-sided polygon)
Example:
/hexagon-c-blue-s-250Supported Attributes:
colorsizexystrokestroke-coloropacityrotatezshadowoctagon
Creates an octagon (8-sided polygon)
Example:
/octagon-c-purple-s-250Supported Attributes:
colorsizexystrokestroke-coloropacityrotatezshadowarrow
Creates an arrow shape
Example:
/arrow-c-blue-w-350-h-175Supported Attributes:
colorwidthheightxystrokestroke-coloropacityrotatefillzshadowline
Creates a horizontal line
Example:
/line-c-black-x-400-y-225-s-600-sw-15Supported Attributes:
colorsizexystrokeopacityrotatezphoto
Creates a photo placeholder icon
Example:
/photo-c-blue-w-450-h-330Supported Attributes:
colorwidthheightxystrokestroke-coloropacityzText Elements
Add text overlays to your images using the text element. Text supports custom fonts, sizes, colors, positions, alignment, and weight. Always specify x and y coordinates for text positioning, as text doesndoesn'tapos;t have a default position like shapes do.
Basic Text
Simple text with default styling
/text-value-Hello-WorldText with Color
Colored text
/text-value-Hello-World-color-blueText with Size
Custom font size
/text-value-Hello-World-color-black-size-96Text with Position
Positioned text
/text-value-Hello-World-color-white-x-400-y-225-size-72Bold Text
Bold font weight
/text-value-Hello-World-color-black-size-80-weight-boldText Alignment
Left, center, or right aligned text
/text-value-Left-Aligned-color-black-x-200-y-225-size-64-align-leftImportant Notes:
- Use hyphens (-) in text-value to represent spaces (e.g., Hello-World becomes "Hello World")
- Always specify x and y coordinates for text positioning
- Text size is in pixels and affects both width and height proportionally
- Use weight-bold for bold text, or omit for normal weight
- Alignment (align-left, align-center, align-right) affects text relative to the x position
Backgrounds
Set the canvas background using the background element. Backgrounds should be placed first in your URL, before any shapes or text. You can use solid colors or gradient presets. Backgrounds are drawn first, so all other elements appear on top of them.
Solid Color Background
Single color background
/background-color-blue/circle-color-white-size-150Sunset Gradient
Beautiful sunset gradient preset
/background-gradient-sunset/text-value-Sunset-color-white-x-400-y-225-size-96Ocean Gradient
Ocean blue gradient preset
/background-gradient-ocean/text-value-Ocean-color-white-x-400-y-225-size-96Background Syntax:
background-color-COLOR- Solid color backgroundbackground-gradient-sunset- Sunset gradient presetbackground-gradient-ocean- Ocean gradient preset
More gradient presets may be added in the future. Backgrounds are always drawn first, regardless of position in URL.
Attributes Reference
Complete reference of all attributes you can use to customize elements. Attributes are specified as key-value pairs separated by hyphens. The order of attributes doesndoesn'tapos;t matter.
Color & Styling
colorSet fill color (named colors or hex)
/circle-color-blueValues: red, blue, green, yellow, orange, purple, pink, black, white, gray, #ff00aa, etc.
strokeStroke width in pixels
/circle-color-blue-stroke-4Values: Number (e.g., 4, 8, 12)
stroke-colorStroke color
/circle-color-blue-stroke-4-stroke-color-whiteValues: Any color name or hex
fillFill style
/circle-outlineValues: solid, outline
opacityOpacity level (0-1)
/circle-color-blue-opacity-0.5Values: 0.0 to 1.0
Size & Dimensions
sizeUniform size for shapes
/circle-color-blue-size-150Values: Number in pixels
widthWidth in pixels
/rectangle-color-blue-width-200Values: Number in pixels
heightHeight in pixels
/rectangle-color-blue-height-100Values: Number in pixels
Position
xX position from left edge (or use percentage like x-50p or x-0.5)
/circle-c-blue-x-300Values: Number in pixels, x-50p (50%), x-0.5 (decimal), or x-50% (URL-encode % as %25)
yY position from top edge (or use percentage like y-50p or y-0.5)
/circle-c-blue-y-200Values: Number in pixels, y-50p (50%), y-0.5 (decimal), or y-50% (URL-encode % as %25)
zZ-index for layering
/circle-c-blue-z-2Values: Number (higher = on top)
anchorAnchor point for positioning
/circle-c-blue-anchor-top-leftValues: center, top-left, top-right, bottom-left, bottom-right, top, bottom, left, right
Text Attributes
valueText content (use hyphens or | for spaces, | for line breaks)
/text-value-Hello-WorldValues: Any text (hyphens become spaces, | creates line breaks)
size / fontSizeFont size in pixels
/text-value-Hello-fs-96Values: Number in pixels
fontFont family
/text-value-Hello-f-ArialValues: Font name
weightFont weight
/text-value-Hello-fw-boldValues: normal, bold, light
alignText alignment
/text-value-Hello-a-leftValues: left, center, right, top, bottom
Transformations
rotate / rRotation angle in degrees
/square-c-blue-r-45Values: 0-360 degrees
opacity / oOpacity level (0-1)
/circle-c-blue-o-0.5Values: 0.0 to 1.0
Visual Effects
shadowDrop shadow effect
/circle-c-blue-shadow-mediumValues: small, medium, large, or custom blur-offset-color
radius / brBorder radius for rectangles
/rectangle-c-blue-br-20Values: Number in pixels
points / ptsNumber of points for stars/polygons
/star-c-yellow-pts-6Values: Number (e.g., 6 for 6-pointed star)
Groups & Layouts
group / sceneGroup multiple elements together
/group-layout-row-g-20/circle-c-red/square-c-blueValues: group or scene
layoutLayout arrangement for groups
/group-layout-rowValues: row, column, grid
gap / gGap between elements in layout
/group-layout-row-g-30Values: Number in pixels
padding / pPadding inside groups
/group-p-20Values: Number in pixels
Human-Readable Aliases
bgAlias for background
/bg-c-grayValues: Same as background
cAlias for color
/circle-c-blueValues: Same as color
sAlias for size
/circle-s-100Values: Same as size
wAlias for width
/rectangle-w-200Values: Same as width
hAlias for height
/rectangle-h-100Values: Same as height
fsAlias for fontSize
/text-fs-32Values: Same as fontSize
fwAlias for fontWeight
/text-fw-boldValues: Same as weight
swAlias for strokeWidth
/circle-sw-4Values: Same as stroke
scAlias for strokeColor
/circle-sc-whiteValues: Same as stroke-color
oAlias for opacity
/circle-o-0.5Values: Same as opacity
rAlias for rotate
/square-r-45Values: Same as rotate
brAlias for radius
/rectangle-br-15Values: Same as radius
ptsAlias for points
/star-pts-6Values: Same as points
Color Reference
DrawByURL supports named colors and hex color codes. Named colors are easier to read and remember, while hex codes give you precise control over colors. You can use either format in the color attribute.
red
#ff0000blue
#0000ffgreen
#008000yellow
#ffff00orange
#ffa500purple
#800080pink
#ffc0cbblack
#000000white
#ffffffgray/grey
#808080cyan
#00ffffmagenta
#ff00fflime
#00ff00navy
#000080teal
#008080sky
#87ceebforest
#228b22coral
#ff7f50Using Hex Colors:
You can use hex codes with or without the # symbol. Both formats work:
/circle-color-#ff00aa-size-150/circle-color-ff00aa-size-150Hex colors are useful when you need exact color matching or want to use colors not in the named list.
Complex Examples
These examples demonstrate how to combine multiple elements to create more sophisticated designs. Notice how elements are separated by forward slashes, and how the order affects the final composition.
Multiple Shapes (Short Syntax)
Use aliases for cleaner URLs
/circle-c-blue-s-250-x-200-y-200/square-c-red-s-280-x-400-y-250/triangle-c-green-s-250-x-600-y-200Shape with Multiline Text
Add multiline text using | separator
/bg-c-navy/text-value-DrawByURL|Create Images|By Typing URLs-c-white-fs-72-a-center-x-400-y-200Grouped Layout
Use groups with automatic layouts
/group-layout-row-g-50-x-400-y-225/circle-c-white-s-180-shadow-medium/square-c-white-s-180-shadow-medium/triangle-c-white-s-180-shadow-mediumRounded Rectangle with Shadow
Combine border radius and shadows
/rectangle-c-blue-w-500-h-250-br-30-shadow-large-x-400-y-225New Shapes Collection
Try heart, diamond, hexagon, and more
/heart-c-red-s-250-x-200-y-200/diamond-c-green-w-250-h-200-x-400-y-200/hexagon-c-blue-s-250-x-600-y-200Percentage Positioning
Use relative positioning with percentages
/circle-c-blue-s-250-x-50p-y-50p/square-c-red-s-200-x-25p-y-25pCustom Star Points
Create stars with custom point counts
/star-c-yellow-s-300-pts-6-x-300-y-225/star-c-gold-s-300-pts-8-x-500-y-225Grid Layout Scene
Arrange multiple shapes in a grid
/scene-layout-grid-w-700-h-500-x-400-y-225/circle-c-red-s-150/square-c-blue-s-150/triangle-c-green-s-150/heart-c-pink-s-150Query Parameters
Query parameters control the canvas dimensions and output format. They're added to the end of your URL after a question mark (?). Multiple parameters are separated by ampersands (&). These parameters don't affect the visual design, only the canvas size and file format.
widthCanvas width in pixels
?width=1200heightCanvas height in pixels
?height=600formatImage format
?format=jpegqualityImage quality (for JPEG/WebP)
?quality=90Example with Multiple Parameters:
/circle-color-blue-size-150?width=1200&height=800&format=jpeg&quality=95This creates a blue circle on a 1200x800 pixel canvas, exported as a JPEG with 95% quality. The default canvas size is 800x450 pixels, and the default format is PNG.
Best Practices
Follow these guidelines to create better images and avoid common mistakes. These practices help ensure your URLs are readable, maintainable, and produce the expected results.
1. Element Order Matters
Elements are drawn in the order they appear in the URL. Draw backgrounds first, then shapes, then text. Later elements appear on top of earlier ones.
/background-color-blue/circle-color-white/text-value-Hello2. Use Z-Index for Complex Layering
When you need precise control over which elements appear on top, use the z attribute. Higher z values appear on top. Without z-index, elements are drawn in URL order.
/circle-color-blue-z-1/square-color-red-z-23. Always Position Text Explicitly
Text doesndoesn'tapos;t have a default position like shapes do. Always specify x and y coordinates for text to ensure it appears where you want it.
/text-value-Hello-x-400-y-225-size-964. Set Canvas Size for Your Use Case
Use query parameters to set the exact canvas size you need. Default is 800x450, but you might need 1200x630 for OpenGraph images, 1080x1080 for Instagram, etc.
/circle-color-blue?width=1080&height=10805. Use Hyphens for Spaces in Text
Replace spaces in text-value with hyphens. They'll be automatically converted to spaces in the rendered text.
/text-value-Hello-World → "Hello World"6. Keep URLs Readable
While attribute order doesndoesn'tapos;t matter, keeping a consistent order (type, color, size, position, etc.) makes URLs easier to read and debug.
/circle-color-blue-size-150-x-400-y-225