dicebear

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 7, 2025 License: MIT Imports: 14 Imported by: 0

README

Dicebear-go

dicebear-go is a package that wraps around DiceBear's API. This allows you to easily generate tons of unique avatars in Go. The API can generate more than 1 sexdecillion (that's 17 zeroes!) unique avatars!

dicebear-go version Go Version License Code of Conduct

Other languages

If you want to use Dicebear avatars but don't use Golang, you can use the dicebear Python package or the official JS/TS package.

Table of contents

Installation

Install the dicebear-go package using the following command:

go get -u github.com/jvherck/dicebear-go

Basic usage

package main

import (
	"fmt"
	"log"

	"github.com/jvherck/dicebear-go"
)

func main() {
	// Create a new avatar with the "adventurer" style and a random seed
	avatar, err := dicebear.NewAvatar(dicebear.Adventurer, "", nil, nil)
	if err != nil {
		log.Fatalf("Failed to create avatar: %v", err)
	}

	// Get the avatar URL
	fmt.Println("Avatar URL:", avatar.URL())

	// Save the avatar as an SVG file
	outputPath := "avatar.svg"
	_, err = avatar.Save(dicebear.SVG, outputPath, false)
	if err != nil {
		log.Fatalf("Failed to save avatar: %v", err)
	}

	fmt.Println("Avatar saved to:", outputPath)
}

/*
Output:
Avatar URL: https://api.dicebear.com/9.x/adventurer/svg?seed=random-seed
Avatar saved to: avatar.svg
*/

Contributing

We welcome contributions from the community! Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated. Find out in our Contributing Guide how to contribute to this project.

Credits

Special thanks to Dicebear (Florian Körner) for making this amazing API and to all artists for creating all the awesome avatars and artwork!

Disclaimer: this repository and its owner are not affiliated with DiceBear.

Licenses and privacy policy

Documentation

Index

Constants

View Source 
const (
	BaseURL = "https://api.dicebear.com/9.x" // Base URL for DiceBear API
	Timeout = 30                             // Default timeout in seconds
)

Variables

View Source 
var (
	ErrInvalidOption       = errors.New("invalid option")
	ErrNetworkRequest      = errors.New("network request failed")
	ErrImageSave           = errors.New("failed to save image")
	ErrFileOperationFailed = errors.New("file operation failed")
)

Common errors

View Source 
var AllFormats = []Format{SVG, WEBP, AVIF, PNG, JPG, JPEG, JSON}

AllFormats is a list of all available image formats.

View Source 
var AllStyles = []Style{
	Adventurer, AdventurerNeutral, Avataaars, AvataaarsNeutral,
	BigEars, BigEarsNeutral, BigSmile, Bottts, BotttsNeutral,
	Croodles, CroodlesNeutral, Dylan, FunEmoji, Glass, Icons,
	Identicon, Initials, Lorelei, LoreleiNeutral, Micah, Miniavs,
	Notionists, NotionistsNeutral, OpenPeeps, Personas,
	PixelArt, PixelArtNeutral, Rings, Shapes, Thumbs,
}

AllStyles is a list of all available avatar styles.

Functions

func IsValidFormat 

func IsValidFormat(format Format) bool

IsValidFormat checks if a format is valid.

func IsValidStyle 

func IsValidStyle(style Style) bool

IsValidStyle checks if a style is valid.

func RandomString 

func RandomString(length int) string

RandomString generates a random string of specified length.

Types

type Avatar 

type Avatar struct {
	// contains filtered or unexported fields
}

Avatar represents a DiceBear avatar.

func NewAvatar 

func NewAvatar(style Style, seed string, options *Options, customParams map[string]string) (*Avatar, error)

NewAvatar creates a new Avatar with the given style and seed.

func (*Avatar) CustomParams 

func (a *Avatar) CustomParams() map[string]string

CustomParams returns the custom parameters of the avatar.

func (*Avatar) Customize 

func (a *Avatar) Customize(params map[string]string, replace bool) error

Customize sets custom parameters for the avatar.

func (*Avatar) Edit 

func (a *Avatar) Edit(style Style, seed string, options *Options) error

Edit modifies the avatar parameters and updates the URL.

func (*Avatar) GetBytes 

func (a *Avatar) GetBytes(format Format) ([]byte, error)

GetBytes returns the avatar bytes in the specified format.

func (*Avatar) GetSchema 

func (a *Avatar) GetSchema() (map[string]interface{}, error)

GetSchema returns the schema for the avatar style.

func (*Avatar) GetText 

func (a *Avatar) GetText(format Format) (string, error)

GetText returns the avatar text in the specified format.

func (*Avatar) Options 

func (a *Avatar) Options() *Options

Options returns the options of the avatar.

func (*Avatar) Save 

func (a *Avatar) Save(format Format, outputFilepath string, overwrite bool) (string, error)

Save saves the avatar to disk.

func (*Avatar) Seed 

func (a *Avatar) Seed() string

Seed returns the seed of the avatar.

func (*Avatar) Style 

func (a *Avatar) Style() Style

Style returns the style of the avatar.

func (*Avatar) URL 

func (a *Avatar) URL() string

URL returns the URL of the avatar.

func (*Avatar) URLWithFormat 

func (a *Avatar) URLWithFormat(format Format) (string, error)

URLWithFormat returns the URL of the avatar with the specified format.

func (*Avatar) View 

func (a *Avatar) View(format Format) error

View opens the avatar in the default web browser.

type Color 

type Color string

Color represents a color in hex or "transparent" format.

func NewColor 

func NewColor(hexCode string) (Color, error)

NewColor validates and creates a new Color from a hex code.

func NewRandomColor 

func NewRandomColor() Color

NewRandomColor generates a random hex color.

type Format 

type Format string

Format represents the available image formats. 

const (
	SVG  Format = "svg"  // Scalable Vector Graphics
	WEBP Format = "webp" // WebP format
	AVIF Format = "avif" // AVIF format
	PNG  Format = "png"  // Portable Network Graphics
	JPG  Format = "jpg"  // JPEG format
	JPEG Format = "jpeg" // JPEG format (alias)
	JSON Format = "json" // JSON format
)

type HTTPResponseError 

type HTTPResponseError struct {
	StatusCode int
	Body       string
}

func (*HTTPResponseError) Error 

func (e *HTTPResponseError) Error() string

type ImageFormatError 

type ImageFormatError struct{ Format Format }

func (*ImageFormatError) Error 

func (e *ImageFormatError) Error() string

type InvalidColorError 

type InvalidColorError struct{ Code string }

func (*InvalidColorError) Error 

func (e *InvalidColorError) Error() string

type InvalidStyleError 

type InvalidStyleError struct{ Style Style }

Error types with context

func (*InvalidStyleError) Error 

func (e *InvalidStyleError) Error() string

type Options 

type Options struct {
	Flip               bool   `json:"flip,omitempty"`
	Rotate             int    `json:"rotate,omitempty"`
	Scale              int    `json:"scale,omitempty"`
	Radius             int    `json:"radius,omitempty"`
	Size               int    `json:"size,omitempty"`
	BackgroundColor    Color  `json:"-"`
	BackgroundType     string `json:"backgroundType,omitempty"`
	BackgroundRotation int    `json:"backgroundRotation,omitempty"`
	TranslateX         int    `json:"translateX,omitempty"`
	TranslateY         int    `json:"translateY,omitempty"`
	RandomizeIDs       bool   `json:"randomizeIds,omitempty"`
}

Options defines avatar customization options.

func DefaultOptions 

func DefaultOptions() *Options

DefaultOptions returns the default avatar options.

type Style 

type Style string

Style represents the available avatar styles. 

const (
	Adventurer        Style = "adventurer"         // Friendly adventurer style
	AdventurerNeutral Style = "adventurer-neutral" // Neutral adventurer style
	Avataaars         Style = "avataaars"          // Avatar style inspired by avataaars
	AvataaarsNeutral  Style = "avataaars-neutral"  // Neutral avataaars style
	BigEars           Style = "big-ears"           // Big ears style
	BigEarsNeutral    Style = "big-ears-neutral"   // Neutral big ears style
	BigSmile          Style = "big-smile"          // Big smile style
	Bottts            Style = "bottts"             // Bottts style
	BotttsNeutral     Style = "bottts-neutral"     // Neutral bottts style
	Croodles          Style = "croodles"           // Croodles style
	CroodlesNeutral   Style = "croodles-neutral"   // Neutral croodles style
	Dylan             Style = "dylan"              // Dylan style
	FunEmoji          Style = "fun-emoji"          // Fun emoji style
	Glass             Style = "glass"              // Glass style
	Icons             Style = "icons"              // Icons style
	Identicon         Style = "identicon"          // Identicon style
	Initials          Style = "initials"           // Initials style
	Lorelei           Style = "lorelei"            // Lorelei style
	LoreleiNeutral    Style = "lorelei-neutral"    // Neutral lorelei style
	Micah             Style = "micah"              // Micah style
	Miniavs           Style = "miniavs"            // Miniavs style
	Notionists        Style = "notionists"         // Notionists style
	NotionistsNeutral Style = "notionists-neutral" // Neutral notionists style
	OpenPeeps         Style = "open-peeps"         // Open peeps style
	Personas          Style = "personas"           // Personas style
	PixelArt          Style = "pixel-art"          // Pixel art style
	PixelArtNeutral   Style = "pixel-art-neutral"  // Neutral pixel art style
	Rings             Style = "rings"              // Rings style
	Shapes            Style = "shapes"             // Shapes style
	Thumbs            Style = "thumbs"             // Thumbs style
)

func RandomStyle 

func RandomStyle() Style

RandomStyle returns a random avatar style.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.