Overview
Render shareable PNG cards from JSON with text, images, progress bars, Discord avatars, and shapes.
Guide
Overview
Build shareable PNG cards from JSON. Layer text, images, progress bars, Discord avatars, and shape rectangles with pixel positioning, transparency, and variable placeholders like {username}.
Enable beta in dashboard settings before calling Card Builder endpoints.
Visual editor
The dashboard Card Builder (/dashboard/cards) includes a drag-and-drop canvas, mobile-friendly layout, a Layers panel to rename, reorder, select, and delete elements, text presets (Header, Subtitle, Label, Body), and built-in templates (Level, Economy, Welcome, Rank Badge, Stats, Quote).
Copy the generated JSON from the editor and send it to POST /api/cards/build.
Limits
- Card size: 50-2400 px width and height
- Up to 200 elements per card
- Output is a hosted PNG URL valid for 30 days
Corner radius
border_radius is a percentage from 0 (square) to 100 (full circle on the shorter side). Use 100 for circular avatars and profile images. Progress bars use the bar height as the reference for pill-shaped ends.
Layering
Higher layer values render on top. Use the dashboard Layers panel or set layer manually in JSON.
Use POST /api/cards/build for full layouts or POST /api/cards/quote for a quick quote card. Expand an element type below for field reference.
Type: text
Renders custom text with font, size, color, alignment, weight, and style. Supports {variable} placeholders from the request variables object.
Use text_gradient_stops (array of two or more colors) and text_gradient_direction (degrees, default 90) for gradient text instead of a solid color.
Key fields: text, text_size, font, color, align, vertical_align, font_weight, font_style, position, size, layer, transparency.
Type: image
Renders an image from a URL or base64 data URI.
border_radius is a percentage: 0 for square corners, 100 for a full circle (based on the shorter side of the element).
Key fields: url, border_radius, position, size, layer, transparency.
Type: progressbar
Draws a fill bar for health, XP, or completion meters.
border_radius is a percentage; 50 on a thin bar gives rounded pill ends.
Key fields: value, max, progress_color, bg_color, border_radius, position, size, layer.
Type: discord_profile
Renders a Discord user's avatar. Requires a Discord bot token saved in dashboard settings, plus an API key or signed-in dashboard session.
user_id accepts a raw snowflake (17-20 digits) or a mention (<@123>). If the bot cannot fetch the user, the API falls back to Discord's default avatar for that ID.
border_radius: 100 renders a perfect circle. Set size.width and size.height to the avatar diameter.
Key fields: user_id, border_radius, position, size, layer, transparency.
Type: rectangle
Draws a filled rectangle with optional stroke. Use for panels, dividers, badges, and background blocks behind text.
Key fields: fill_color, stroke_color, stroke_width, border_radius, position, size, layer, transparency.
fill_color accepts hex or rgba strings. Variables are substituted in color fields.
The card object sets canvas size and background.
| Field | Description |
|---|---|
width, height | Canvas size in pixels (50-2400) |
bg_type | color (default), gradient, or image |
bg | Solid color, gradient start color, or image URL when bg_type is image |
bg_gradient_stops | Array of color stops when bg_type is gradient |
bg_gradient_direction | Gradient angle in degrees (default 135) |
Use cases
- Create rank, level, welcome, and economy cards for Discord bots
- Generate motivational quote images for social media
- Build dynamic cards with variables such as {username} and {level}
- Layer panels and dividers behind text with rectangle elements
- Design cards in the dashboard editor and export JSON for your bot
Limits
Endpoints
/api/cards/buildBuild a custom card from a JSON description and return a hosted PNG URL (valid 30 days)
{
"card": {
"width": 800,
"height": 200,
"bg": "#1e293b",
"bg_type": "color"
},
"elements": [
{
"type": "rectangle",
"fill_color": "rgba(99,102,241,0.15)",
"stroke_color": "rgba(99,102,241,0.3)",
"stroke_width": 1,
"border_radius": 12,
"position": {
"x": 20,
"y": 20
},
"size": {
"width": 760,
"height": 160
},
"layer": 1
},
{
"type": "discord_profile",
"user_id": "{user_id}",
"border_radius": 100,
"position": {
"x": 40,
"y": 40
},
"size": {
"width": 80,
"height": 80
},
"layer": 2
},
{
"type": "text",
"text": "{username}",
"text_size": 26,
"font": "Poppins",
"color": "#f8fafc",
"font_weight": "bold",
"position": {
"x": 140,
"y": 48
},
"size": {
"width": "auto",
"height": "auto"
},
"layer": 3
},
{
"type": "progressbar",
"value": 65,
"max": 100,
"progress_color": "#6366f1",
"bg_color": "#0f172a",
"border_radius": 50,
"position": {
"x": 140,
"y": 110
},
"size": {
"width": 520,
"height": 18
},
"layer": 4
}
],
"variables": {
"username": "Player",
"user_id": "123456789012345678"
}
}Required: card and elements. Optional: variables object for {placeholder} substitution. Supported element types: text, badge (pill with centred text: text, text_size, font, color, fill_color), image, discord_profile, qrcode (data, fg_color, bg_color), rectangle, ellipse, polygon (sides, star, inner_ratio, fill_color), divider, progressbar, ring (circular progress: value, max, progress_color, bg_color, thickness, label), chart (values as "4,7,5", chart_style bars/line/area, bar_color). Card options: width, height, bg, bg_type (color, gradient, image), bg_gradient_stops, bg_gradient_direction, bg_fit (cover, contain, stretch), bg_overlay (a colour laid over the background), radius (rounded card corners in px, transparent outside). Every element also accepts rotation (degrees, around its centre) and a drop shadow: shadow_color, shadow_blur, shadow_x, shadow_y. Discord avatars use the bot token linked to your API key or session.
/api/cards/quoteQuick quote-card convenience endpoint. Returns a hosted PNG URL (valid 30 days).
{
"quote": "Discipline is choosing what you want most over what you want now.",
"author": "Author",
"width": 1200,
"height": 675,
"bgColor": "#0a0a0b",
"textColor": "#ffffff",
"fontSize": 52,
"italic": true,
"bold": false,
"showQuotes": false
}Required: quote. Optional: author, width, height, bgColor, textColor, fontSize, italic, bold, showQuotes.
Example request
{
"method": "POST",
"path": "https://api.auralink.dev/api/cards/quote",
"headers": {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
"body": {
"quote": "Discipline is choosing what you want most over what you want now.",
"author": "Author",
"width": 1200,
"height": 675,
"bgColor": "#0a0a0b",
"textColor": "#ffffff",
"fontSize": 52,
"italic": true,
"bold": false,
"showQuotes": false
}
}