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/names
List names
GET/api/v1/names/{id}
Get name by id
GET/api/v1/names/{id}/avatars
List name avatars
GET/api/v1/names/random
Get random name
POST/api/v1/names
Create name

Avatars

GET/api/v1/avatars
List avatars
GET/api/v1/avatars/{id}
Get avatar by id
GET/api/v1/avatars/random
Get random avatar
POST/api/v1/avatars
Create avatar

Identities

GET/api/v1/identities
List identities
GET/api/v1/identities/{id}
Get identity by id
GET/api/v1/identities/random
Get random identity
POST/api/v1/identities
Create identity

Dictionaries

GET/api/v1/companies
List companies
GET/api/v1/countries
List countries
GET/api/v1/languages
List languages

Error Responses

400Bad Request
Invalid request body
404Not Found
Resource not found
429Too Many Requests
Rate limit exceeded
500Internal Server Error
Unexpected 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 stored qualified names with a country, an explicit male or female gender, and ethnicity. 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, an explicit male or female gender, and AI-selected ethnicity. Missing country or gender values are selected before generation; the AI chooses language and ethnicity together so they correlate. 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 identities. Supports the same filters and pagination as GET /api/v1/avatars.

Example

GET
/api/v1/identities/{id}

Load an identity by its ID. Missing, inaccessible, and pending identities return 404.

Example

GET
/api/v1/identities/random

Return a random public or caller-owned private identity.

Example

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

POST
/api/v1/identities

Create an 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 be qualified, including a country, explicit gender, and ethnicity. Optional country or gender values must match it.

Supply optional titleId, complete location, phone, style, age, quality, and visibility. Company and department are defined by the title. Public identities reject caller-supplied location or phone values; omitted values are generated independently. Streams emit generatingName, generatingIdentityData, and generatingAvatar. Pending replies contain identityRequestId; retry with only that property.

Billing includes qualified-name generation when needed, structured identity-data generation when location or phone is missing, and avatar generation. Exact fully resolved duplicates are reused.

Rate limit: 3 requests per minute per authenticated user.

Example

Dictionaries

GET
/api/v1/companies

List demo companies with nested departments and titles. Each title includes its default age and style.

Example

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/{id}
curl "https://nametoavatar.com/api/v1/names/{id}/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/{id}
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"}'
curl "https://nametoavatar.com/api/v1/identities?gender=female&country=Japan&page=1"
curl https://nametoavatar.com/api/v1/identities/{id}
curl https://nametoavatar.com/api/v1/identities/random
curl -X POST https://nametoavatar.com/api/v1/identities
curl https://nametoavatar.com/api/v1/companies
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