> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatars API

> Cleariflow Avatars API is a fast, lightweight, modern, and RESTful JSON API for creating highly customizable avatar images with a person's name or initials to improve your user experience.

Using this service is straightforward: simply provide your `api_key` along with a `name`, and the system will create an avatar image that corresponds to the initials of the provided name.

## Getting started

### REST

The Avatars API follows the same architectural pattern as all Cleariflow services, built around REST principles. It employs predictable, resource-focused URLs and utilizes HTTP status codes for error communication.

### HTTPS

The Avatars API mandates that all data transmission be protected using TLS 1.2 or higher encryption protocols.

### API Versions

Every Cleariflow service includes versioning. The Avatars API presently operates on Version 1.

### Your API Key

Your API key serves as your exclusive authentication credential for accessing the Cleariflow Avatars API. Keep in mind that every Cleariflow service possesses its own distinct API key, meaning you'll require separate keys for different services like Avatars and Email Validation APIs. To verify your requests, you must include your API key in the base URL.

### Base URL

```
https://avatars.cleariflow.com/v1/
```

### Validation endpoint

The Cleariflow Avatars API only needs your exclusive API key and the user's name for avatar generation:

```
https://avatars.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& name = Alexander Rodriguez
```

This request was processed successfully, and the resulting avatar for the specified name appears below:

<img alt="Avatar for Alexander Rodriguez" src="https://mintcdn.com/cleariflow/JFqWO7lxhDZeTQpu/assets/cf_avatar.png?fit=max&auto=format&n=JFqWO7lxhDZeTQpu&q=85&s=45fdc40cc251d6313c13a9c620b320b7" width="64" height="64" data-path="assets/cf_avatar.png" />

### Request parameters

<ParamField query="api_key" type="String" required>
  Your exclusive API key. Remember that each user possesses unique API keys for every Cleariflow service, so your Avatars API key won't function with your IP Geolocation API, for instance.
</ParamField>

<ParamField query="name" type="String" required>
  The name for which you wish to generate an avatar. You can input multiple names (including first, middle, and last), and the service will automatically show two letters in the avatar. You can modify the letter count using the char\_limit parameter below.
</ParamField>

<ParamField query="image_size" type="Integer">
  The dimensions of the square avatar image in pixels. It automatically defaults to 64 pixels, with available sizes ranging from 6 to 512 pixels.
</ParamField>

<ParamField query="image_format" type="String">
  The preferred format for the generated image. It automatically defaults to "png", but you can also choose "svg".
</ParamField>

<ParamField query="font_size" type="Float">
  The font size expressed as a percentage of the image\_size. It automatically defaults to 0.7, with acceptable values between 0.1 and 1.0.
</ParamField>

<ParamField query="char_limit" type="Integer">
  The maximum character count to display in the avatar. It automatically defaults to 2. The actual character count shown may be fewer than this limit, but never more. Character selection prioritizes distinct words first, then the second letter of distinct words.
</ParamField>

<ParamField query="background_color" type="String">
  The hexadecimal color code for the background. It automatically defaults to #335eea. When specifying a hex color, omit the "#" symbol. For example, \&background\_color=e4704a is valid while \&background\_color=#e4704a is invalid.
</ParamField>

<ParamField query="font_color" type="String">
  The hexadecimal color code for the text. It automatically defaults to white (ffffff). When specifying a hex color, omit the "#" symbol. For example, \&font\_color=e4704a is valid while \&font\_color=#e4704a is invalid.
</ParamField>

<ParamField query="is_rounded" type="Boolean">
  Generates a circular avatar image instead of a square one. It automatically defaults to false.
</ParamField>

<ParamField query="is_uppercase" type="Boolean">
  Converts all initials in the avatar to capital letters. It automatically defaults to true.
</ParamField>

<ParamField query="is_italic" type="Boolean">
  Applies italic styling to all initials in the avatar. It automatically defaults to false.
</ParamField>

<ParamField query="is_bold" type="Boolean">
  Applies bold styling to all initials in the avatar. It automatically defaults to false.
</ParamField>