Name to AvatarAPI Docs - Name to Avatar
Everything you need to integrate Name to Avatar into your application.
Generate an avatar and demographic inference from a person's name.
Request Body
{
"name": "Yuki Tanaka",
"style": "professional,casual,creative",
"age": "adult,senior",
"country": "Japan"
}name string, required if no name_id — The full name to analyze. Max 100 characters, 1-5 words.
name_id UUID, optional — ID of a name returned by POST /api/v1/name. When provided, the name and language are loaded from the database (returns 404 if not found). Provide either name or name_id.
country string, optional — One of the exact country strings returned by GET /api/v1/countries. Can be used with either name or name_id. If both name_id and country are provided and conflict with the name record's country, the request returns 400.
style string, optional — Avatar style. Use one value or a comma-separated set to pick one at random, for example "professional", "casual", "creative", or "professional,casual,creative". Defaults to "professional".
age string, optional — Apparent age of the avatar. Use one value or a comma-separated set to pick one at random, for example "child", "teenager", "adult", "senior", or "adult,senior". Defaults to "adult".
Query Parameters
stream=1 optional — Return newline-delimited JSON (NDJSON) with progress events: analyzing, generating, then complete (with the full response) or error.
In streaming mode, the generating event may include determined_country when country is already known.
{
"step": "generating",
"inference": {
"gender": {
"value": "female",
"confidence": 0.82
},
"ethnicity": {
"value": "East Asian",
"confidence": 0.88
},
"country": {
"value": "unknown",
"confidence": 0.43
}
},
"determined_country": "Japan"
}Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name_id": "661f9500-f39c-52e5-b827-557766550000",
"name": "Yuki Tanaka",
"normalized_name": "yuki tanaka",
"latin_name": "yuki tanaka",
"avatar_url": "https://storage.example.com/avatars/abc123.png",
"inference": {
"gender": {
"value": "female",
"confidence": 0.82
},
"ethnicity": {
"value": "East Asian",
"confidence": 0.88
},
"country": {
"value": "Japan",
"confidence": 0.79
}
}
}id — UUID of the stored avatar (omitted if storage failed).
name_id — UUID of the name used to generate the avatar (present only when name_id was provided in the request).
name — Sanitized name as submitted, preserving original casing.
normalized_name — Normalized (lowercased) name used as a dedupe key.
latin_name — Latin-script transliteration of the name (lowercase). When name_id is provided, the stored latin name from the name record is used. Otherwise, this is inferred by the AI.
inference.country — If country is determined from the name record or explicitly provided in the request, the response uses that country with confidence 1 (`100%`).
Confidence Threshold
If any inference field has a confidence score below 0.55, its value is automatically set to "unknown". The raw confidence score is always returned. If country is determined externally (name record or request parameter), country is overridden in the final response to the determined value at `100%`.
Example (cURL)
curl -X POST https://nametoavatar.com/api/v1/avatar \
-H "Content-Type: application/json" \
-d '{"name": "Yuki Tanaka", "style": "professional,casual,creative", "age": "adult,senior", "country": "Japan"}'Example — Streaming (cURL)
curl -X POST "https://nametoavatar.com/api/v1/avatar?stream=1" \
-H "Content-Type: application/json" \
-d '{"name": "Yuki Tanaka", "country": "Japan"}'Example (JavaScript)
const response = await fetch("/api/v1/avatar", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name: "Yuki Tanaka", style: "professional,casual,creative", age: "adult,senior", country: "Japan" }),
});
const data = await response.json();
console.log(data.avatar_url);
console.log(data.name);
console.log(data.inference);List stored avatars with filtering and pagination. This is the endpoint used by the public /avatars page.
Query Parameters
gender optional - one of male, female, or unisex.
style optional - one of professional, casual, creative.
age optional - one of child, teenager, adult, or senior.
country optional - one of the exact values returned by GET /api/v1/countries.
page and page_size optional - positive integers. Defaults are page=1 and page_size=24.
Response
{
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Yuki Tanaka",
"latin_name": "yuki tanaka",
"avatar_url": "https://storage.example.com/avatars/abc123.png",
"style": "professional",
"age": "adult",
"gender": "female",
"country": "Japan",
"country_source": "record",
"created_at": "2026-04-29T08:30:00.000Z"
}
],
"filters": {
"gender": "female",
"style": "professional",
"age": null,
"country": "Japan"
},
"pagination": {
"page": 1,
"page_size": 24,
"total": 17,
"total_pages": 1,
"has_previous": false,
"has_next": false
}
}Example (cURL)
curl "https://nametoavatar.com/api/v1/avatars?gender=female&style=professional&country=Japan&page=1"Generate a random, culturally authentic personal name. Rate limited to 10 requests per minute.
Request Body — Language
{
"language": "fr"
}Request Body — Country
{
"country": "Japan"
}language string, optional — two-letter language code (ISO 639-1 for almost all; see note on tv). Provide a single code ("ja"), comma-separated codes ("fr,de,ja") to pick one at random, or omit for a fully random language.
Most codes match ISO 639-1. The exception is tv: this API uses it for Tuvaluan (Tuvalu). It is not an official ISO 639-1 code (linguistic registries use ISO 639-2/3 tvl; tv is also Tuvalu's country-code TLD).
country string, optional — Country name (e.g. "Japan", "Switzerland"). The API picks a language spoken in that country and generates an appropriate name. Cannot be combined with language.
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Marie Dupont",
"latin_name": "marie dupont",
"language": "fr",
"language_name": "French"
}id — UUID of the stored name (omitted if storage failed).
latin_name — Latin-script (romanized) version of the name, always present. For languages already using Latin script, this is the lowercased name without diacritics.
language_name — Human-readable name of the language (e.g. "French", "Japanese").
country — Present only when the request used the country parameter.
Example — Language (cURL)
curl -X POST https://nametoavatar.com/api/v1/name \
-H "Content-Type: application/json" \
-d '{"language": "ja"}'Example — Country (cURL)
curl -X POST https://nametoavatar.com/api/v1/name \
-H "Content-Type: application/json" \
-d '{"country": "Switzerland"}'List all supported country names. Use these values with the country parameter in POST /api/v1/name and POST /api/v1/avatar.
Response
["Afghanistan", "Albania", ..., "Zimbabwe"]JSON array of 195 country name strings, sorted alphabetically.
Example (cURL)
curl https://nametoavatar.com/api/v1/countriesList all supported language codes (ISO 639-1 plus the non-standard tv for Tuvaluan — see POST /api/v1/name). Use the code values with the language parameter in POST /api/v1/name.
Response
[
{
"code": "aa",
"name": "Afar"
},
{
"code": "ab",
"name": "Abkhazian"
},
{
"code": "...",
"name": "..."
},
{
"code": "zu",
"name": "Zulu"
}
]JSON array of objects with code (two-letter identifier; ISO 639-1 except tv, which is API-specific) and name (English label).
Example (cURL)
curl https://nametoavatar.com/api/v1/languages{
"error": "Invalid request. Provide a valid name (1-5 words, 100 characters max)."
}{
"error": "Not found"
}{
"error": "The API is busy right now. Please try again in a moment."
}{
"error": "Something went wrong. Please try again later."
}