How do I authenticate with this API?
Create an API key in your Datpaq dashboard and send it with each request as a bearer token in the Authorization header.
User Avatar API
PNG · WebP · SVG
Canvas + Sharp.js
50 / 15 min · rate limit
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.
10–1000 px · sizes3 formats · png · webp · svg5 MB · upload limit50 / 15 min · rate limit
Loading user avatar playground
/api/v1/user-avatar
Endpoints, at a glance.
Six routes.
One generates avatars, one accepts uploads, the rest cover metadata, health and metrics. All GET endpoints support query-string auth.
One generates avatars, one accepts uploads, the rest cover metadata, health and metrics. All GET endpoints support query-string auth.
GET/api/v1/user-avatar
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.
POST/upload-icon
Upload custom icon
Multipart form upload (max 5 MB, image/* only). Returns a path you can pass back as uploadedIcon.
GET/avatar-metadata
Accessibility metadata
JSON with ARIA descriptions, capability lists and size constraints - handy for client-side discovery.
GET/health
Service health
Status, uptime, version and a correlationId. Root / redirects here.
GET/metrics
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.
PNGDEFAULT
Canvas-rendered raster. Universal compatibility, drop-in replacement for img src. Best for product UIs that need a no-questions-asked file.
Content-Typeimage/png
WebPEFFICIENT
Sharp.js conversion with compression tracking. ~30% smaller than PNG with no visible quality loss. Use when bandwidth matters.
Content-Typeimage/webp
SVGA11Y
Native vector with role="img" and aria-label baked in. Scales to any size, inlines into your DOM, plays nicely with assistive tech.
Content-Typeimage/svg+xml
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.
400
Invalid size
Size must be an integer between 10 and 1000. Out-of-range values are rejected with a clear message.
400
Invalid color
Use a hex code (#ff0000) or a CSS color name. XSS-flavored values get rejected before rendering.
400
Invalid shape / format
Shape must be "circle" or "square". Format must be "png", "webp", or "svg". Any other value returns 400.
400
File too large
Uploads are capped at 5 MB. Larger files get a clean 400 instead of a partial write.
400
Invalid file type
Only image/* MIME types pass validation. PNG, JPG, and SVG are accepted.
429
Rate limited
50 requests per 15-minute window per IP. Response includes retryAfter in seconds.
500
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" }
Working example
See the User Avatar sample app
An open-source single-page app that calls this API from JavaScript, with auth and rendering wired up.
FAQ
API questions developers ask first.
Is there a free tier?
Yes. Datpaq APIs include a free tier for building, testing, and small production workloads before you move to a paid plan.
What format do requests and responses use?
Datpaq APIs use REST over HTTPS and return JSON by default. Endpoint docs show the supported methods, query parameters, request bodies, and response fields.
Where can I see limits and errors?
Each API documents rate limits, validation rules, and error responses in the landing page and API docs so integrations can retry and fail cleanly.
Ship avatars in a single GET.
Query-string auth, no SDK required. Drop the URL into an <img>and you're done.