Get started

User Avatar API

Create highly customizable avatar images with a person's name or initials to improve your user experience.
Get your free api key
Test it out
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.


Serving millions of calls to 100,000+ developers and end users worldwide

Why 10,000+ developers love Abstract's APIs

Easy to implement and maintain

We built Abstract because most of the API's we've used in the past simply weren't great. Our APIs are built the way we think API's should be: with excellent documentation, multiple easy to use libraries, and tutorials to get you started.

Speed and scale built into everything we do

Something like IP geolocation is probably part of a critical business processes and flow, so we built it (as all of our APIs) for use at scale and at blazing speeds. These aren't just marketing phrases, but fundamental features of our APIs.

Reliable uptime and great support

Developers trust Abstract because of our reliable uptime and excellent technical support that will help get you live quickly, keep you running smoothly, and resolve any issues you have fast regardless of where you are or what you're building.

The User Avatar API creates flexible avatar images from names or initials

Simple yet flexible REST API

The User Avatar API is built with the right mix of simplicity, speed, and flexibility, so you can focus on the parts of your code that matter and still have beautiful, reliable user avatars.

Highly customizable typograpy

Our highly customizable avatar creation process lets you specify fonts, weights, alignment, or style. Make your avatars match your brand and your interface easily.

Specify background and font colors

It's important to have full control over the look and feel of something as visible as your user avatars, so you can set everything for the avatar's color and size.

Multiple scripts and languages supported

Non-Latin scripts and lanuages supported, including Arabic, Hebrew, Chinese, Japanese, and Thai so you can support users from around the world.

Retina support included

Create super crisp and clear avatars even on high resolution screens with highly flexible and high quality images that leave your site or app looking great for users.

Bank-level security for all queries

Abstract is about more than speed and features. We also care deeply about security, so all data that is sent and processed is secured via 256-bit SSL encryption (HTTPS).

Simple and cost-effective pricing



no card

  • 250,000 requests / month




  • UNLIMITED Requests

User Avatar API Documentation


The User Avatar API, like all of Abstract's APIs, is organized around REST. It is designed to use predictable, resource-oriented URL's and to use HTTP status codes to indicate errors.


All communications with the User Avatar API must be secured TLS 1.2 or greater.

API Versions

All of Abstract's API are versioned. The User Avatar API is currently on Version 1.

Your API Key

Your API key is your unique authentication key to be used to access Abstract's User Avatar API. Note that each of Abstract's API has a unique API key, so you will need different keys to access the User Avatar and IP Geolocation APIs, for example. To authenticate your requests, you will need to append your API key to the base URL.

Base URL

User Avatar API Request Parameters




name required


The name you want to create an avatar for. You can submit multiple names (such as first, middle, and last), and the API will default to displaying two letters in the avatar. You can change the number of letters displayed with the char_limit parameter below.

api_key required


Your unique API key. Note that each user has unique API keys for each of Abstract's APIs, so your IP Geolocation API key will not work for as your User Avatar key, for example.



The size of the square avatar image in pixels. It defaults to 32 pixels, and is available in sizes from 6 to 512 pixels.



The desired format of the returned image. It defaults to "svg", but can also be specified as "png".



The size of the font as a percent of the image_size. It defaults to 0.5, but it can be set between 0.1 and 1.0.



The maximum number of characters displayed in the avatar. It defaults to 2. The actual number of characters displayed can be less than this number, but it cannot be more. The characters will first be chosen from distinct words, then from the second letter of distinct words. For example, with a char_limit of 2,  the string "John" will return "JO", "John Smith" will return "JS", and "John Patrick Smith" will return "JS".



The hex color for the background. It defaults to 335eea. When including a hex color, you do not need to include the "#". So &background_color=e4704a would be valid and &background_color=#e4704a would be invalid.



The hex color for the font. It defaults to white, i.e.,ffffff. When including a hex color, you do not need to include the "#". So &font_color=e4704a would be valid and &font_color=#e4704a would be invalid.



Sets the initials in the avatar to all capitals. It defaults to true.



Sets the initials in the avatar to all italics. It defaults to false.



Sets the initials in the avatar to bold. It defaults to false.

Example User Avatar Request With All Default Parameters

To create a user avatar via the API, the absolute minimum required is your unique API key and at least 1 character in the name.
    ? apikey = YOUR_UNIQUE_API_KEY
    & name = John Smith

This simple request would return the following image:

Response and Error Codes

Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.






Everything worked as expected.


Bad request

Bad request



The request was unacceptable. Typically due to the API key missing or incorrect.


Internal Server Error

The request could not be completed due to an error on the server side.


Service Unavailable

The server was unavailable.

Frequently Asked Questions
about Abstract's User Avatar API

Why would I use an API to create user avatars?

When users sign up for an app or website, it's common to allow them to upload an image of themselves. However, in many cases users don't do that right away (or ever!), and you and they are stuck with a bunch of bland and empty spaces where an image should be. You can automatically spice up the interface by adding a custom avatar for that user that's created from their name or initials.

How does the User Avatar API work with other services like Gravtar?

Gravtar describes their service as providing "an image that follows you from site to site appearing beside your name when you do things like comment or post on a blog. Avatars help identify your posts on blogs and web forums, so why not on any site?". This is a very popular option for getting a user's image, but it's not always available. Users of Abstract's User Avatar API will often use our service as a fall back when a gravtar cannot be found.

What languages and character types do you support?

We support most characters (including emoji!). We're also rolling out support for additional languages and characters like Arabic, Bengali, Hebrew, Chinese, Japanese, and Thai.

Developers around the world love Abstract's User Avatar API

Woohoo! No more boring empty images in our user list. We looked at several options to handle this including building and maintaining it in house (no thank you!) but finally found that Abstract handles this. The flexibility is pretty great, but we mainly love the simplicity and not needing to think about it.

Michael Ludwig

Our app didn't have a great fallback if users didn't upload their images, which made our image-heavy UI look pretty weak with a bunch of empty gray squares. We now have really colorful avatars that make the UI look great without requiring the users or us to do a lot of work.

Chris Stillins

Super simple implementation. Great documentation. Great response and up times. Great support team. Lots of new features coming each month. What's not to love with the API? And we love that it's part of Abstract so we can use all their other services too like IP Geolocation and Email Validation.

Cyan Pullman

User Avatar API Changelog

Last Updated on 

August 11, 2020

August 11, 2020


Added new text formatting and color options

July 1, 2020


Improved support for Hebrew, Arabic, and other right-to-left scripts

July 6, 2020


Added additional avatar color options


Get  FREE credits to start today.

Get thousands of API calls for free across all Abstract APIs.

Frequently Asked Questions
About Subscription & Pricing

What does the API cost?

Each of our API's has a free plan as well as several paid options, which offer a greater number of requests, a higher level of data quality, and greater speed for higher prices. Please see the page above or sign into your account to view pricing for each API.

Do you have a free trial or free options for your API's?

Absolutely! We want you to try before you buy. Each of our API's has a free tier with a generous usage allowance for you to try the product out and verify that the speed and data quality work for you.

What payment options do you offer?

We use Stripe to accept payment via major debit and credit cards (Visa, Mastercard, American Express). If you cannot use those payment methods, then contact us at team at to arrange for an alternative payment method.

Can I upgrade or downgrade my subscription?

Yes, you can upgrade or downgrade your subscription at any time by visiting your dashboard. If you upgrade in the middle of a billing cycle, you will be charged a pro-rated amount for your new plan through the end of the billing cycle.

Can I cancel at any time?

Yes, all of our subscriptions are month to month. You can cancel at any time, and you will not be charged again at the end of your billing cycle.

How can I cancel my subscription?

You can cancel your subscription at any time from your dashboard. Once canceled, your subscription will be active until the end your current billing cycle, and then it will be automatically moved to the free plan.

What happens if I go over my monthly quota for requests?

If your API usage exceeds the monthly limit set by your plan, then you will be charged a fee for each call over your limit. At the end of your billing period, your usage will reset again.

What if I need more requests or something else that's not offered in your plans?

We do offer enterprise plans with custom features and pricing in limited circumstances. If our public pricing plans don't work for you, then contact us (team at and we'll work something out.

Do you offer any discounts?

While we don't normally offer discounts, we do make exceptions for certain types of users and use cases. If you are a student or are engaged in academic work, or are working on a non-profit or open source project, we're happy to offer you discounts for our API's. Just email us at team at

Do you offer discounts for annual or quarterly payments?

All of our plans are currently paid month to month. We will be launching annual plans at a discount soon. If you're interested in an annual plan in the meantime, just contact us and we'll set you up.

What happens if my payment method expires?

We will typically attempt to charge your payment method up to three times after it fails. If we're still unable to collect payment, then your subscription will be automatically canceled and you'll be moved to the free plan.

Can I use the API's for a commercial project?

Yes, a paid tier of our API may be used in conjunction with a commercial project. The free tiers of our API's may not be used in commercial projects.