API Docs

Everything you need to integrate Name to Avatar into your application

Avatars

POST/api/v1/avatarsCreate Avatar GET/api/v1/avatarsList Avatars GET/api/v1/avatars/randomGet Random Avatar GET/api/v1/avatars/{id}Get Avatar by ID

Names

POST/api/v1/namesCreate Name GET/api/v1/names/randomGet Random Name GET/api/v1/names/{id}Get Name by ID

Other

GET/api/v1/countriesList Countries GET/api/v1/languagesList Languages

Avatars

Create, load, list, and share avatar records. Every avatar endpoint returns the same avatar item shape.

POST

/api/v1/avatars

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.

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

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

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 a valid x-api-key to bypass canonical-avatar reuse.

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.

{
  "step": "generating",
  "inference": {
    "gender": {
      "value": "female",
      "confidence": 0.82
    },
    "ethnicity": {
      "value": "East Asian",
      "confidence": 0.88
    },
    "country": {
      "value": "Japan",
      "confidence": 0.43
    },
    "location": {
      "value": "French Polynesia",
      "confidence": 0.77
    }
  },
  "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",
  "style": "professional",
  "age": "adult",
  "inference": {
    "gender": {
      "value": "female",
      "confidence": 0.82
    },
    "ethnicity": {
      "value": "East Asian",
      "confidence": 0.88
    },
    "country": {
      "value": "Japan",
      "confidence": 1
    },
    "location": {
      "value": "French Polynesia",
      "confidence": 0.77
    }
  },
  "created_at": "2026-04-29T08:30:00.000Z"
}

This exact avatar item shape is also returned by GET /api/v1/avatars items, GET /api/v1/avatars/random, and GET /api/v1/avatars/{id}.

Examples

curl -X POST https://nametoavatar.com/api/v1/avatars \
  -H "Content-Type: application/json" \
  -d '{"name": "Yuki Tanaka"}'

curl -X POST "https://nametoavatar.com/api/v1/avatars?stream=1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Yuki Tanaka"}'

GET

/api/v1/avatars

List stored public avatars with filtering and pagination.

Query Parameters

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 page_size - optional positive integers. Defaults are 1 and 24.

Response

{
  "items": [
    {
      "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",
      "style": "professional",
      "age": "adult",
      "inference": {
        "gender": {
          "value": "female",
          "confidence": 0.82
        },
        "ethnicity": {
          "value": "East Asian",
          "confidence": 0.88
        },
        "country": {
          "value": "Japan",
          "confidence": 1
        },
        "location": {
          "value": "French Polynesia",
          "confidence": 0.77
        }
      },
      "created_at": "2026-04-29T08:30:00.000Z"
    }
  ],
  "filters": {
    "name": null,
    "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
  }
}

Each items[] entry uses the same avatar item shape shown above.

Example

curl "https://nametoavatar.com/api/v1/avatars?gender=female&style=professional&country=Japan&page=1"

GET

/api/v1/avatars/random

Return one random public avatar. "Public" uses the same visibility rule as the avatar catalog.

{
  "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",
  "style": "professional",
  "age": "adult",
  "inference": {
    "gender": {
      "value": "female",
      "confidence": 0.82
    },
    "ethnicity": {
      "value": "East Asian",
      "confidence": 0.88
    },
    "country": {
      "value": "Japan",
      "confidence": 1
    },
    "location": {
      "value": "French Polynesia",
      "confidence": 0.77
    }
  },
  "created_at": "2026-04-29T08:30:00.000Z"
}

curl https://nametoavatar.com/api/v1/avatars/random

Try it out

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

GET

/api/v1/avatars/{id}

Load one stored avatar by its UUID.

id must be the avatar UUID.

{
  "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",
  "style": "professional",
  "age": "adult",
  "inference": {
    "gender": {
      "value": "female",
      "confidence": 0.82
    },
    "ethnicity": {
      "value": "East Asian",
      "confidence": 0.88
    },
    "country": {
      "value": "Japan",
      "confidence": 1
    },
    "location": {
      "value": "French Polynesia",
      "confidence": 0.77
    }
  },
  "created_at": "2026-04-29T08:30:00.000Z"
}

curl https://nametoavatar.com/api/v1/avatars/<avatarId>

Names

Generate names or load stored name records. Every name endpoint returns the same name item shape.

POST

/api/v1/names

Generate a random, culturally authentic personal name.

Request Body

{
  "language": "fr"
}

{
  "country": "Japan"
}

language - optional two-letter code, or a comma-separated set to pick one at random.

country - optional supported country 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",
  "country": "France",
  "created_at": "2026-04-29T08:30:00.000Z"
}

This exact name item shape is also returned by GET /api/v1/names/random and GET /api/v1/names/{id}.

Examples

curl -X POST https://nametoavatar.com/api/v1/names \
  -H "Content-Type: application/json" \
  -d '{"language": "ja"}'

curl -X POST https://nametoavatar.com/api/v1/names \
  -H "Content-Type: application/json" \
  -d '{"country": "Switzerland"}'

GET

/api/v1/names/random

Return one random stored name from the database.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Marie Dupont",
  "latin_name": "marie dupont",
  "language": "fr",
  "language_name": "French",
  "country": "France",
  "created_at": "2026-04-29T08:30:00.000Z"
}

curl https://nametoavatar.com/api/v1/names/random

Try it out

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

GET

/api/v1/names/{id}

Load one stored name by its UUID.

id must be the name UUID.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Marie Dupont",
  "latin_name": "marie dupont",
  "language": "fr",
  "language_name": "French",
  "country": "France",
  "created_at": "2026-04-29T08:30:00.000Z"
}

curl https://nametoavatar.com/api/v1/names/<nameId>

Other

Lookup endpoints for supported countries and language codes.

GET

/api/v1/countries

List all supported country names. Use them with POST /api/v1/names and POST /api/v1/avatars.

["Afghanistan", "Albania", ..., "Zimbabwe"]

curl https://nametoavatar.com/api/v1/countries

GET

/api/v1/languages

List all supported language codes. Use them with POST /api/v1/names.

[
  {
    "code": "aa",
    "name": "Afar"
  },
  {
    "code": "ab",
    "name": "Abkhazian"
  },
  {
    "code": "...",
    "name": "..."
  },
  {
    "code": "zu",
    "name": "Zulu"
  }
]

curl https://nametoavatar.com/api/v1/languages

Error Responses

400Bad Request

{
  "error": "Invalid request body."
}

404Not Found

{
  "error": "Not found"
}

429Too Many Requests

{
  "error": "Too many requests for this endpoint. Please try again later."
}

500Internal Server Error

{
  "error": "Something went wrong. Please try again later."
}