Dicebear Avatars Getting Started: Quick Integration Guide (2026)

Getting started overview

Integrating Dicebear Avatars into a project primarily involves two methods: utilizing the HTTP API directly or incorporating the official JavaScript library. Both approaches facilitate the generation of customizable avatars, suitable for various applications such as user profiles, placeholder images, or mock data. This guide focuses on the immediate steps required to get an avatar generated, from account creation to the first successful API call or library usage.

Before making requests, developers need to understand the basic authentication mechanisms and the structure of avatar generation requests. Dicebear offers a free tier that supports up to 500,000 avatar creations per month, making it accessible for initial development and smaller projects. For higher volumes or advanced features, paid plans are available, as detailed on their pricing page.

The following table summarizes the key steps to get started:

Create an account and get keys

To begin using Dicebear Avatars beyond the basic, unauthenticated public API, you must first create an account. An account grants access to a personalized API key, which is essential for tracking usage, accessing specific styles, and ensuring rate limits are applied correctly. While the Dicebear public API allows some avatar generation without an API key, an authenticated account provides more control and higher usage limits, particularly for commercial or production applications.

1. Navigate to the Dicebear Website: Open your web browser and go to Dicebear's homepage.
2. Sign Up: Look for a 'Sign Up' or 'Get Started' button. You will typically be prompted to provide an email address and create a password, or sign up using an existing social account (e.g., Google).
3. Verify Email (if required): After signing up, check your email for a verification link from Dicebear. Click this link to activate your account.
4. Access Dashboard: Once logged in, you will be directed to your personal dashboard. This is where you manage your account, view usage statistics, and find your API key.
5. Locate API Key: Within the dashboard, there should be a section clearly labeled 'API Keys' or similar. Your unique API key will be displayed here. It is a string of alphanumeric characters. Treat this key as sensitive information, similar to a password, to prevent unauthorized usage of your avatar generation quota. For security best practices, consider environment variables for storing API keys in production, as outlined in Google Developers authentication guidance.

Your API key is generally required when making requests to the Dicebear API, typically passed as a query parameter or an HTTP header, depending on the specific API endpoint and client library used.

Your first request

After obtaining your API key, you can make your first request to generate an avatar. This section demonstrates how to do this using both the HTTP API and the JavaScript library.

Using the HTTP API

The Dicebear HTTP API allows you to generate avatars by constructing a URL with various parameters. The API key is typically appended to the URL. For detailed information on available styles and options, refer to the Dicebear HTTP API reference.

Example: Generate a random avatar (HTTP GET request)

This example generates a random avatar using the 'bottts' style. Replace YOUR_API_KEY with the key obtained from your dashboard.

curl "https://api.dicebear.com/7.x/bottts/svg?seed=random&apiKey=YOUR_API_KEY" > avatar.svg

In this command:

• https://api.dicebear.com/7.x/bottts/svg is the base URL for the Bottts style, requesting an SVG format.
• ?seed=random specifies that a random avatar should be generated.
• &apiKey=YOUR_API_KEY passes your API key for authentication and usage tracking.
• > avatar.svg saves the generated SVG image to a file named avatar.svg.

You can paste the URL (after replacing YOUR_API_KEY) directly into a web browser to see the generated avatar. For programmatic access, curl or a similar HTTP client library in your chosen programming language (e.g., requests in Python, fetch in JavaScript) can be used.

Using the JavaScript Library

For JavaScript-based projects (e.g., web applications, Node.js), using the Dicebear JavaScript library is often more convenient. It provides a programmatic interface for avatar generation without manually constructing URLs.

Example: Generate an avatar with the JavaScript library

First, install the library using npm or yarn:

npm install @dicebear/collection @dicebear/core

Then, create a JavaScript file (e.g., generateAvatar.js) with the following content. Remember to replace YOUR_API_KEY.

import { createAvatar } from '@dicebear/core';
import { bottts } from '@dicebear/collection';

async function generateDicebearAvatar() {
  const avatar = createAvatar(bottts, {
    seed: 'JohnDoe',
    apiKey: 'YOUR_API_KEY', // Your Dicebear API key
    dataUri: true, // Request data URI for direct embedding
  });

  const svgDataUri = await avatar.toDataUri();
  console.log('Generated SVG Data URI:', svgDataUri);

  // To get raw SVG string:
  // const svgString = await avatar.toSvg();
  // console.log('Generated SVG String:', svgString);

  // In a browser environment, you could embed this directly:
  // document.getElementById('avatar-container').innerHTML = ``;
}

generateDicebearAvatar();

This script:

• Imports createAvatar from @dicebear/core and the bottts style from @dicebear/collection.
• Calls createAvatar with the desired style and options, including a seed for consistent avatar generation and your apiKey.
• Uses toDataUri() to get the avatar as a data URI, which can be directly embedded in HTML <img> tags or CSS backgrounds.

For more advanced usage and available options, consult the Dicebear JavaScript library documentation.

Common next steps

After successfully generating your first avatar, consider these common next steps to further integrate and optimize your use of Dicebear Avatars:

1. Explore Avatar Styles and Options: Dicebear offers a wide range of avatar styles (e.g., pixel-art, open-peeps, bottts) each with unique customization options. Review the documentation for different styles to find one that best fits your application's aesthetic. Experiment with parameters like colors, accessories, and facial features.
2. Integrate into Your Application: Incorporate the avatar generation into your user registration flow, profile pages, or comment sections. Depending on your frontend framework (React, Vue, Angular), you might use components that fetch and display the avatar.
3. Caching Strategies: To optimize performance and reduce API calls, implement client-side or server-side caching for generated avatars. Since avatars are often based on a seed (e.g., a user ID), the same seed will always produce the same avatar. Cache results to avoid re-requesting identical images. This is a common strategy for optimizing web content delivery.
4. Error Handling: Implement robust error handling for API requests. The Dicebear API will return specific HTTP status codes and error messages for issues like invalid API keys, rate limits, or malformed requests. Your application should gracefully handle these scenarios.
5. Monitor Usage: Regularly check your Dicebear dashboard to monitor your API usage against your plan's limits. This helps prevent unexpected interruptions due to exceeding your quota.
6. Security Considerations: If generating avatars on the client-side, ensure your API key is not exposed to the public, especially if you are on a paid plan with higher limits. For most production applications, server-side generation is recommended to protect your API key.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Invalid API Key:
  • Symptom: HTTP 401 Unauthorized or similar error message.
  • Solution: Double-check that you have copied your API key correctly from your Dicebear dashboard. Ensure there are no leading or trailing spaces. Verify that the key is passed in the correct parameter (e.g., apiKey query parameter).
• Incorrect URL or Endpoint:
  • Symptom: HTTP 404 Not Found or HTTP 400 Bad Request.
  • Solution: Compare your request URL against the Dicebear HTTP API documentation. Ensure the version (e.g., 7.x), style name (e.g., bottts), and format (e.g., svg) are correct.
• Rate Limiting:
  • Symptom: HTTP 429 Too Many Requests.
  • Solution: If you are making many requests in a short period without an API key, you might hit public rate limits. Using your authenticated API key increases your limits. If using a key, check your dashboard for current usage and consider implementing exponential backoff for retries, as recommended for Stripe API rate limits.
• Network Issues:
  • Symptom: Connection timeouts or network unreachable errors.
  • Solution: Verify your internet connection. If making requests from a restricted network, check firewall rules that might block outbound HTTP/HTTPS traffic to api.dicebear.com.
• Ad Blocker/Browser Extensions:
  • Symptom: Avatars not loading in a browser, but working via curl.
  • Solution: Some browser extensions or ad blockers might interfere with external image requests, especially if the URL structure is flagged. Test in an incognito window or with extensions disabled.
• JavaScript Library Not Installed/Imported Correctly:
  • Symptom: TypeError: createAvatar is not a function or similar.
  • Solution: Ensure you have correctly installed @dicebear/core and the specific style collection (e.g., @dicebear/collection) using npm or yarn. Verify your import statements match the library's documentation.