Name to Avatar
AvatarsAPI DocsDemo
Loading account...

API Docs

Everything you need to integrate Name to Avatar into your application

Send an API key in the x-api-key header to authenticate generation requests and access your private avatar records.

Names

GET/api/v1/namesList namesGET/api/v1/names/{id}Get name by idGET/api/v1/names/{id}/avatarsList name avatarsGET/api/v1/names/randomGet random namePOST/api/v1/namesCreate name

Avatars

GET/api/v1/avatarsList avatarsGET/api/v1/avatars/{id}Get avatar by idGET/api/v1/avatars/randomGet random avatarPOST/api/v1/avatarsCreate avatar

Identities

GET/api/v1/identitiesList identitiesGET/api/v1/identities/{id}Get identity by idGET/api/v1/identities/randomGet random identityPOST/api/v1/identitiesCreate identity

Dictionaries

GET/api/v1/countriesList countriesGET/api/v1/languagesList languages

Error Responses

400Bad RequestInvalid request body404Not FoundResource not found429Too Many RequestsRate limit exceeded500Internal Server ErrorUnexpected server error

Names

GET
/api/v1/names

List stored names with filtering and pagination.

Query Parameters

name - optional fuzzy match against the stored name.

language - optional two-letter code from GET /api/v1/languages.

country - optional country from GET /api/v1/countries.

gender - optional comma-separated list containing male and/or female.

isQualified=true - require a stored country and an explicit male or female gender. An optional gender narrows the qualified results.

page and pageSize - optional positive integers. Defaults are 1 and 24.

Example

GET
/api/v1/names/{id}

Load a stored name by its id.

id must be a name UUID.

Example

GET
/api/v1/names/{id}/avatars

List avatars associated with a stored name.

id must be a name UUID. The endpoint supports the same filtering and pagination query parameters as GET /api/v1/avatars.

Anonymous requests include public catalog avatars. A session or x-api-key also includes private avatars owned by the authenticated user.

Example

GET
/api/v1/names/random

Return one random stored name from the database.

Example

Fetch a live response from /api/v1/names/random.

POST
/api/v1/names

Generate a random, culturally authentic personal name.

Request Body

language - optional two-letter code, or a comma-separated set to pick one at random. Cannot be combined with country or isQualified.

country - optional supported country name. Cannot be combined with language.

gender - optional explicit gender override. Supported values: male and female.

isQualified=true - generate with a stored country and an explicit male or female gender, selecting either missing value at random. Only the boolean value true is accepted.

Example

Avatars

GET
/api/v1/avatars

List stored public avatars with filtering and pagination.

Query Parameters

nameId - optional UUID for an exact stored name.

name - optional fuzzy match against the stored name.

gender - optional, one of male, female, or unisex.

style - optional, one of professional, casual, or creative.

age - optional, one of child, teenager, adult, or senior.

country - optional country from GET /api/v1/countries.

page and pageSize - optional positive integers. Defaults are 1 and 24.

Example

GET
/api/v1/avatars/{id}

Load a stored avatar by its id.

id must be an avatar UUID.

Example

GET
/api/v1/avatars/random

Return one random public avatar. "Public" uses the same visibility rule as the GET /api/v1/avatars endpoint.

Example

Fetch a live response from /api/v1/avatars/random.

POST
/api/v1/avatars

Generate an avatar and demographic inference from a person's name.

Request Body

name - string, required if no nameId.

nameId - UUID from POST /api/v1/names.

country - optional country from GET /api/v1/countries.

gender - optional explicit gender override. Supported values: male and female. When combined with nameId, it must match the stored generated name.

style - optional avatar style, or a comma-separated set to pick one at random. Supported values: professional, casual, and creative. If not specified, professional is used by default.

age - optional avatar age, or a comma-separated set to pick one at random. Supported values: child, teenager, adult, and senior. If not specified, adult is used by default.

forceNew - optional boolean. Requires authentication through a session or x-api-key to refresh the avatar.

Query Parameters

stream=1 returns NDJSON progress events: analyzing, generating, complete, or error.

Duplicate in-flight requests may return 202 with a pending payload and Retry-After.

Example

Example (Streamed)

Identities

GET
/api/v1/identities

List accessible qualified identities. Supports the same filters and pagination as GET /api/v1/avatars.

Example

GET
/api/v1/identities/{id}

Load an accessible identity by avatar ID. Missing, inaccessible, and non-identity avatars return 404.

Example

GET
/api/v1/identities/random

Return a random public or caller-owned private identity.

Example

POST
/api/v1/identities

Create a qualified identity. Authentication by session or x-api-key is required.

Send an eligible nameId, or omit it to generate a name with a resolved country and male or female gender. A selected name must already contain both fields. Optional country or gender values must match it.

Avatar appearance, visibility, quality, forceNew, slot reuse, and stream=1 behave like avatar creation. Automatic-name streams emit generatingName and nameGenerated before avatar progress. Pending replies contain identityRequestId; retry with only that property.

Billing is the combined name-plus-avatar charge when a name is generated, or the avatar charge for selected names. Rate limit: 3 requests per minute per authenticated user.

Example

Dictionaries

GET
/api/v1/countries

List all supported countries.

Example

GET
/api/v1/languages

List all supported languages.

Example

Error Responses

400Bad Request
404Not Found
429Too Many Requests
500Internal Server Error
curl "https://nametoavatar.com/api/v1/names?name=Marie&language=fr&gender=female&page=1"
curl https://nametoavatar.com/api/v1/names/<nameId>
curl "https://nametoavatar.com/api/v1/names/<nameId>/avatars?style=professional&page=1"
curl https://nametoavatar.com/api/v1/names/random
{
  "country": "Japan",
  "gender": "female"
}
curl -X POST https://nametoavatar.com/api/v1/names \
-H "Content-Type: application/json" \
-d '{"country": "Switzerland", "gender": "female"}'
curl "https://nametoavatar.com/api/v1/avatars?gender=female&style=professional&country=Japan&page=1"
curl https://nametoavatar.com/api/v1/avatars/<avatarId>
curl https://nametoavatar.com/api/v1/avatars/random
{
  "name": "Yuki Tanaka",
  "gender": "female",
  "style": "professional,casual,creative",
  "age": "adult,senior",
  "country": "Japan"
}
curl -X POST https://nametoavatar.com/api/v1/avatars \
-H "Content-Type: application/json" \
-d '{"name": "Yuki Tanaka", "gender": "female"}'
curl -X POST "https://nametoavatar.com/api/v1/avatars?stream=1" \
-H "Content-Type: application/json" \
-d '{"name": "Yuki Tanaka"}'
https://nametoavatar.com/api/v1/identities?gender=female&country=Japan&page=1
https://nametoavatar.com/api/v1/identities/<identityId>
https://nametoavatar.com/api/v1/identities/random
https://nametoavatar.com/api/v1/identities
curl https://nametoavatar.com/api/v1/countries
curl https://nametoavatar.com/api/v1/languages
{
  "error": "Invalid request body."
}
{
  "error": "Not found"
}
{
  "error": "Too many requests for this endpoint. Please try again later."
}
{
  "error": "Something went wrong. Please try again later."
}
© 2026 Name to Avatar
Created by Sergey Atroshchenko