Personalized avatars, on demand.
Drop in a name and get a polished initials avatar back. Pass a URL, an uploaded icon, a hex color, a shape, or a pattern — the API renders it server-side in PNG, WebP, or accessible SVG.
Live · client-rendered
Tune every parameter. See the result.
Adjust the controls below to configure your avatar. The preview updates instantly. Hit Generate to call the real API.
live preview · svg rendered client-side
/api/v1/user-avatar
Endpoints, at a glance.
One generates avatars, one accepts uploads, the rest cover metadata, health and metrics. All GET endpoints support query-string auth.
Generate avatar
Returns a PNG, WebP or SVG built from initials, an external image URL, or a previously uploaded icon. 12 query params control look & feel.
Upload custom icon
Multipart form upload (max 5 MB, image/* only). Returns a path you can pass back as uploadedIcon.
Accessibility metadata
JSON with ARIA descriptions, capability lists and size constraints — handy for client-side discovery.
Service health
Status, uptime, version and a correlationId. Root / redirects here.
Prometheus metrics
Generation counts by format & shape, duration histograms, upload stats, conversion rates.
| Parameter | Type | Default | Description |
|---|---|---|---|
| name | string | "A B" | Name for initials generation |
| size | integer | 200 | Avatar dimensions in pixels (10–1000) |
| bgColor | string | "#3498db" | Background color (hex or CSS name) |
| textColor | string | "#ffffff" | Text color for initials |
| borderColor | string | "#000000" | Border color |
| borderWidth | integer | 4 | Border thickness in pixels |
| font | string | "Arial" | Font family for initials text |
| shape | string | "circle" | "circle" or "square" |
| pattern | string | "none" | "none" or "dots" |
| format | string | "png" | "png", "webp", or "svg" |
| imageUrl | string | — | External image URL (HTTP/HTTPS, max 500 chars) |
| uploadedIcon | string | — | Path from a previous /upload-icon call |
Output formats
Three formats. One endpoint.
Choose by use-case. PNG for compatibility, WebP for bandwidth, SVG for crisp scaling and screen-reader support.
Canvas-rendered raster. Universal compatibility, drop-in replacement for img src. Best for product UIs that need a no-questions-asked file.
Sharp.js conversion with compression tracking. ~30% smaller than PNG with no visible quality loss. Use when bandwidth matters.
Native vector with role="img" and aria-label baked in. Scales to any size, inlines into your DOM, plays nicely with assistive tech.
cURL · Generate SVG avatar
# Generate a 300px circular SVG avatar from initials curl "https://datpaq.com/api/v1/user-avatar\ ?name=Jane%20Smith&size=300&bgColor=%23cfff5e&textColor=%230b0b0b&shape=circle&format=svg&api_key=your-key" \ -H "x-correlation-id: avatar-12345"
Predictable failures
Errors you can read.
Every failure response carries a correlationId. Status codes are explicit. Validation messages tell you which constraint you broke.
Invalid size
Size must be an integer between 10 and 1000. Out-of-range values are rejected with a clear message.
Invalid color
Use a hex code (#ff0000) or a CSS color name. XSS-flavored values get rejected before rendering.
Invalid shape / format
Shape must be "circle" or "square". Format must be "png", "webp", or "svg". Any other value returns 400.
File too large
Uploads are capped at 5 MB. Larger files get a clean 400 instead of a partial write.
Invalid file type
Only image/* MIME types pass validation. PNG, JPG, and SVG are accepted.
Rate limited
50 requests per 15-minute window per IP. Response includes retryAfter in seconds.
External image error
When imageUrl fails to load, the service falls back to a warning icon and logs the failure for tracing.
400 Bad Request · example response
// 400 Bad Request { "success": false, "error": "Invalid size parameter. Size must be between 10 and 1000 pixels.", "correlationId": "avatar-error456" }
Ship avatars in a single GET.
Query-string auth, no SDK required. Drop the URL into an <img>and you're done.