Avatars
The Avatars operations are for developers who need small images in an integration or a storefront: browser, card brand and country flag icons, initials avatars, QR codes, a resized copy of a remote image, or a screenshot of a web page. On success each call returns one image, PNG unless the operation says otherwise; errors return JSON. Every operation is a GET under /v1/avatars/, with its options in the query string.
Before you call
Every call needs one of the two credentials the gateway accepts: an API key in X-Revenexx-Api-Key, or a Bearer token. An API key must carry the avatars scope (or *); without it the call fails with 403. Send your tenant in X-Revenexx-Tenant on every call; without it the call fails with 400. See Authentication and API keys for how to get and send a credential.
Because a call needs these headers, a plain <img src> pointing at the API does not work, and an API key must not reach the browser. Fetch the image on your server and serve the bytes from there.
curl "https://api.revenexx.com/v1/avatars/qr?text=hello" \
-H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
-H "X-Revenexx-Tenant: acme" \
-o qr.png
Size and aspect ratio
The browser, credit card, flag, remote image and initials operations share one rule for width and height:
When one dimension is specified and the other is 0, the image is scaled with preserved aspect ratio. If both dimensions are 0, the API provides an image at source quality.
The screenshot operation sizes its output differently, see its section. Each operation's default size is in its parameter table.
Browser icon
GET /v1/avatars/browsers/{code} returns the icon of a browser.
| Name | In | Required | Type | Range or default |
|---|---|---|---|---|
code | path | yes | string | One of aa, an, ch, ci, cm, cr, ff, sf, mf, ps, oi, om, op, on. |
width | query | no | integer | 0 to 2000. Default 100. |
height | query | no | integer | 0 to 2000. Default 100. |
quality | query | no | integer | -1 to 100. Default: keep the existing image quality. |
Response: 200 with image/png.
Credit card icon
GET /v1/avatars/credit-cards/{code} returns the icon of a card brand.
| Name | In | Required | Type | Range or default |
|---|---|---|---|---|
code | path | yes | string | One of amex, argencard, cabal, cencosud, diners, discover, elo, hipercard, jcb, mastercard, naranja, targeta-shopping, unionpay, visa, mir, maestro, rupay. |
width | query | no | integer | 0 to 2000. Default 100. |
height | query | no | integer | 0 to 2000. Default 100. |
quality | query | no | integer | -1 to 100. Default: keep the existing image quality. |
Response: 200 with image/png.
Country flag
GET /v1/avatars/flags/{code} returns the flag of a country.
| Name | In | Required | Type | Range or default |
|---|---|---|---|---|
code | path | yes | string | A lowercase ISO 3166-1 alpha-2 country code. The operation knows 195 of them; some codes, such as hk and tw, are not in the list. The API Explorer shows the full list. |
width | query | no | integer | 0 to 2000. Default 100. |
height | query | no | integer | 0 to 2000. Default 100. |
quality | query | no | integer | -1 to 100. Default: keep the existing image quality. |
Response: 200 with image/png.
Remote image
GET /v1/avatars/image fetches a remote image by its URL and resizes it, for example to serve a third-party image from your own server over TLS.
| Name | In | Required | Type | Range or default |
|---|---|---|---|---|
url | query | yes | string (URL) | The image to fetch. See the rules below. |
width | query | no | integer | 0 to 2000. Default 400. |
height | query | no | integer | 0 to 2000. Default 400. |
The url must be publicly reachable and answer 200 with a raster image on the first request. Redirects are not followed, so a URL that redirects answers 404, as does any URL that does not answer 200. An SVG image or an .ico file cannot be decoded and answers 500.
Response: 200 with the image (image/*).
Initials avatar
GET /v1/avatars/initials returns an avatar with the initials of a name.
| Name | In | Required | Type | Range or default |
|---|---|---|---|---|
name | query | no | string | 1 to 128 characters. When omitted, the signed-in user's name or email is used. |
width | query | no | integer | 0 to 2000. Default 500. |
height | query | no | integer | 0 to 2000. Default 500. |
background | query | no | string | A hex colour of 3 or 6 digits, without #. |
Without name and without a signed-in user, the avatar is empty, so pass name when you call with an API key. Without background, the colours come from a theme picked at random for the initials, and the same initials keep the same theme.
The default size is 500x500 px; the parameter descriptions in the spec say 100, which is not what the operation does.
Response: 200 with image/png.
QR code
GET /v1/avatars/qr converts plain text into a QR code image.
| Name | In | Required | Type | Range or default |
|---|---|---|---|---|
text | query | yes | string | 1 to 512 characters. |
size | query | no | integer | 1 to 1000. Default 400. |
margin | query | no | integer | 0 to 10. Default 1. |
download | query | no | boolean | 0 or 1. Default 0. With 1, the response adds a Content-Disposition: attachment header, so a browser downloads the file. |
Response: 200 with image/png.
Web page screenshot
GET /v1/avatars/screenshots renders a web page in a headless browser and returns a screenshot of it.
| Name | In | Required | Type | Range or default |
|---|---|---|---|---|
url | query | yes | string (URL) | The page to capture. |
headers | query | no | object | HTTP headers sent with the browser request. Default: none. |
viewportWidth | query | no | integer | 1 to 1920. Default 1280. |
viewportHeight | query | no | integer | 1 to 1080. Default 720. |
scale | query | no | number | 0.1 to 3. Default 1. |
theme | query | no | string | light or dark. Default light. |
userAgent | query | no | string | 1 to 512 characters. Default: the browser's own. |
fullpage | query | no | boolean | 0 for the viewport only, 1 for the full page scroll. Default 0. |
locale | query | no | string | 1 to 10 characters, for example en-US or fr-FR. Default: the browser's own. |
timezone | query | no | string | One of the listed IANA timezone identifiers, canonically cased, for example America/New_York. Every listed identifier has exactly two segments. Default: the browser's own. |
latitude | query | no | number | -90 to 90. Default 0. |
longitude | query | no | number | -180 to 180. Default 0. |
accuracy | query | no | number | 0 to 100000, in meters. Default 0. |
touch | query | no | boolean | 0 for no touch, 1 for touch enabled. Default 0. |
permissions | query | no | array of strings | Browser permissions to grant, for example geolocation, camera or microphone. Repeat the parameter for each value: permissions=geolocation&permissions=camera. Default: none. |
sleep | query | no | integer | 0 to 10 seconds to wait before the capture. Default 0. |
width | query | no | integer | 0 to 2000. 0 keeps the original width. Default 0. |
height | query | no | integer | 0 to 2000. 0 keeps the original height. Default 0. |
quality | query | no | integer | -1 to 100. Default: keep the existing image quality. |
output | query | no | string | The output format: jpg, jpeg, png, webp, heic, avif or gif. |
UTC and three-segment identifiers such as America/Argentina/Buenos_Aires are refused with 404. The API Explorer lists every accepted timezone and permissions value.
When width and height are set, the image is resized to them. When both are 0, the image keeps its original size.
Response: 200 with the image. The spec declares it as image/png, although output can ask for another format.
Errors
| Status | Operations | When |
|---|---|---|
400 | All | The X-Revenexx-Tenant header is missing, or a parameter is invalid: out of range, not in the allowed list (for example a flag code that is not listed), or too long. |
401 | All | The credential is missing or invalid. |
403 | All | The caller is authenticated but not permitted, for example an API key without the avatars scope. |
404 | image, screenshots | image: the URL could not be fetched or did not answer 200 with an image. screenshots: the page could not be captured, for example with a timezone of UTC. |
429 | All | The tenant's rate limit was exceeded. |
500 | image | The fetched file could not be decoded, for example an SVG or .ico file. |
502 | All | The service behind the route could not be reached or did not answer in time. |
A missing tenant header and the 401, 403, 429 and 502 bodies use the gateway's envelope; see Errors. A 400 for an invalid parameter and a 404 have a different shape: code is the numeric status, message is a readable text, and type names the error, for example general_argument_invalid, avatar_image_not_found or avatar_remote_url_failed. Branch on type.
{
"message": "string",
"code": 404,
"type": "avatar_remote_url_failed",
"version": "string"
}
The body above is built from the spec's schema; message and version vary.