Name to Avatar
AvatarsAPI DocsMCP ServerBlog

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 records.

Names

GET/api/v1/names
List names
GET/api/v1/names/{id}
Get name by id
POST/api/v1/names
Create name
GET/api/v1/names/{id}/avatars
List name avatars
GET/api/v1/names/{id}/identities
List name identities
GET/api/v1/names/random
Get random name

Avatars

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

Products

GET/api/v1/products
List products
GET/api/v1/products/{id}
Get product by id
POST/api/v1/products
Create product
GET/api/v1/products/random
Get random product

Identities

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

Company Roster Templates

GET/api/v1/company-roster-templates
List templates
POST/api/v1/company-roster-templates
Create template
PUT/api/v1/company-roster-templates/{id}
Update template
DELETE/api/v1/company-roster-templates/{id}
Archive template
GET/api/v1/company-roster-templates/{id}/versions
List template versions
GET/api/v1/company-roster-templates/{id}/versions/{version}
Get template version

Company Rosters

GET/api/v1/company-rosters
List rosters
GET/api/v1/company-rosters/{id}
Get roster
POST/api/v1/company-rosters
Create roster
POST/api/v1/company-rosters/summaries
Poll roster summaries
POST/api/v1/company-rosters/{id}/start
Start roster
POST/api/v1/company-rosters/{id}/retry
Retry roster
POST/api/v1/company-rosters/{id}/resume
Resume roster
PUT/api/v1/company-rosters/{id}/discard
Discard pending members

Dictionaries

GET/api/v1/companies
List companies
GET/api/v1/countries
List countries
GET/api/v1/languages
List languages
GET/api/v1/locations
List locations
GET/api/v1/product-categories
List product categories

Error Responses

400Bad Request
Invalid request body
401Unauthorized
Authentication required
402Payment Required
Insufficient credits
403Forbidden
Not authorized
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.

my=true - require authentication and return only names generated by the caller.

page and pageSize - optional positive integers. Defaults are 1 and 24. The maximum pageSize is 100.

Example

GET
/api/v1/names/{id}

Load a stored name by its id.

id must be a name UUID.

Example

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.

Rate limit: 3 requests per minute, tracked per IP for anonymous callers and per user for authenticated callers.

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/{id}/identities

List identities 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/identities.

Anonymous requests include public identities. A session or x-api-key also includes private identities 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.

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.

my=true - require authentication and return only avatars owned by the caller.

page and pageSize - optional positive integers. Defaults are 1 and 24. The maximum pageSize is 100.

Example

GET
/api/v1/avatars/{id}

Load a stored avatar by its id.

id must be an avatar UUID.

Example

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.

Rate limit: 3 requests per minute, tracked per IP for anonymous callers and per user for authenticated callers.

Example

Example (Streamed)

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.

Products

GET
/api/v1/products

List accessible products, newest first.

Public products and private products owned by the authenticated caller are returned. Use visibility to filter by public or private, and categoryId to filter by an exact product category ID. page and pageSize default to 1 and 24; the maximum pageSize is 100. JSON-field searching is not supported.

Example

GET
/api/v1/products/{id}

Load one accessible product by UUID.

Missing and inaccessible products return 404.

Example

GET
/api/v1/products/random

Return one random accessible stored product without generating or charging for it.

Returns 404 when no accessible product exists.

Example

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

POST
/api/v1/products

Generate and store a product. Authentication and an Idempotency-Key header are required.

Choose exactly one mode. JSON mode supplies data and generates only the image. Prompt mode supplies prompt and generates arbitrary-schema JSON followed by its image. Random mode supplies neither field.{ "name": "Forest Green Wireless Speaker", "categoryId": 222, "data": { "type": "wireless speaker", "color": "forest green" }, "quality": "low", "visibility": "public" }{ "prompt": "A compact recycled-aluminum travel coffee grinder", "quality": "medium", "visibility": "private" }{ "quality": "high", "visibility": "public" }Product name and categoryId are optional generation inputs. Category IDs come from GET /api/v1/product-categories. An explicit category is authoritative. JSON mode infers a missing category from the supplied data using AI. Random mode chooses a random category before generating the remaining product, while prompt mode returns the category selected for the generated data. Every stored product and product response includes categoryId. When name is omitted, it is generated from the resolved product JSON. Product data is an arbitrary top-level JSON object. Supplied JSON is preserved semantically and may contain strings, finite numbers, booleans, null, arrays, and nested objects. Limits are 4,000 prompt characters, 65,536 serialized data bytes, and 20 nesting levels.Every mode stores an unchanged 1024x1024 PNG original in the private bucket and a 256x256 PNG derivative in the public bucket. imageUrl is always the direct public URL. Only the owner receives a direct signed hiresImageUrl; public visibility does not grant original access.Quality is low, medium, or high and changes image cost. JSON mode bills one bounded text operation for each missing name or category, plus one image operation. Prompt and random modes produce the category with their product-data operation and bill one bounded text operation plus one image. All modes use a 1.00 billing multiplier.A new result returns 201, a completed replay returns 200, and an in-progress replay returns 202 with Retry-After. Reusing a key with another body returns 409. The endpoint is limited to 3 requests per minute per authenticated user.Add stream=1 to receive NDJSON progress events. Events are generatingProductData, productDataGenerated, inferringProductCategory, productCategoryInferred, generatingProductName, productNameGenerated, generatingProductImage, pending, complete, or error.

Example

Identities

GET
/api/v1/identities

List accessible identities. Supports the same public filters and pagination as GET /api/v1/avatars, plus companyId, titleId, and locationId. The maximum pageSize is 100.

Example

GET
/api/v1/identities/{id}

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

Example

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, locationId, complete location, phone, style, age, quality, and visibility. country and locationId cannot be combined. 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, tracked per IP for anonymous callers and per user for authenticated callers.

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.

Company Roster Templates

GET
/api/v1/company-roster-templates

List accessible public and caller-owned company roster templates.

Optional query parameters: companyId, page, and pageSize. The default pageSize is 24. The maximum pageSize is 100.

Example

POST
/api/v1/company-roster-templates

Create a company roster template. Authentication is required.

Positions require a titleId, accept either country or locationId, and default memberCount to 1.

Example

PUT
/api/v1/company-roster-templates/{id}

Create the next version of an owned template.

expectedVersion prevents overwriting a template that changed since it was loaded.

Example

DELETE
/api/v1/company-roster-templates/{id}

Archive an owned company roster template.

Returns 204 with no response body.

Example

GET
/api/v1/company-roster-templates/{id}/versions

List all accessible versions of a company roster template.

Example

GET
/api/v1/company-roster-templates/{id}/versions/{version}

Load one accessible company roster template version.

Example

Company Rosters

GET
/api/v1/company-rosters

List accessible company rosters with progress and pagination.

Optional query parameters: templateId, status, page, and pageSize. The default pageSize is 24. The maximum pageSize is 100.

Example

GET
/api/v1/company-rosters/{id}

Load an accessible company roster with its member records.

Example

POST
/api/v1/company-rosters

Create a company roster from a template. Authentication is required.

An optional Idempotency-Key header safely replays the original result. A new roster returns 201; a replay returns 200.

Example

POST
/api/v1/company-rosters/summaries

Poll compact summaries for up to 100 accessible rosters.

ids is a required array of roster UUIDs.

Example

POST
/api/v1/company-rosters/{id}/start

Prepare and start generation for an owned pending roster.

Returns the roster with 202 when work was queued, otherwise 200.

Example

POST
/api/v1/company-rosters/{id}/retry

Retry failed members in an owned roster.

Returns 202 with the number of members dispatched.

Example

POST
/api/v1/company-rosters/{id}/resume

Resume generation for an owned paused roster.

Returns 202.

Example

PUT
/api/v1/company-rosters/{id}/discard

Discard pending generation state for one member or all eligible members.

Send either memberId or all: true. Authentication and roster ownership are required.

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

GET
/api/v1/locations

List all supported locations in alphabetical order.

country - optional country from GET /api/v1/countries.page and pageSize - optional positive integers. Defaults are 1 and 50. The maximum pageSize is 200.

Example

GET
/api/v1/product-categories

List all supported Google product categories with their numeric IDs.

Example

Error Responses

400Bad Request
401Unauthorized
402Payment Required
403Forbidden
404Not Found
429Too Many Requests
500Internal Server Error
curl "https://nametoavatar.com/api/v1/names?pageSize=5"
curl https://nametoavatar.com/api/v1/names/{id}
{
  "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/names/{id}/avatars?style=professional"
curl "https://nametoavatar.com/api/v1/names/{id}/identities?style=professional"
curl https://nametoavatar.com/api/v1/names/random
curl "https://nametoavatar.com/api/v1/avatars?gender=female&country=Japan&pageSize=5"
curl https://nametoavatar.com/api/v1/avatars/{id}
{
  "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/avatars/random
curl https://nametoavatar.com/api/v1/products
curl https://nametoavatar.com/api/v1/products/{id}
curl https://nametoavatar.com/api/v1/products/random
curl -X POST https://nametoavatar.com/api/v1/products \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: product-request-001" \
-d '{"name": "Forest Green Wireless Speaker", "categoryId": 222, "data": {"type":"wireless speaker","color":"forest green","features":["Bluetooth","USB-C charging"]}, "quality": "low", "visibility": "public"}'
curl "https://nametoavatar.com/api/v1/identities?gender=female&pageSize=5"
curl https://nametoavatar.com/api/v1/identities/{id}
curl -X POST https://nametoavatar.com/api/v1/identities
curl https://nametoavatar.com/api/v1/identities/random
curl "https://nametoavatar.com/api/v1/company-roster-templates?pageSize=5"
curl -X POST https://nametoavatar.com/api/v1/company-roster-templates \
-H "Content-Type: application/json" \
-d '{"companyId": "880e8400-e29b-41d4-a716-446655440000", "visibility": "private", "name": "Engineering team", "positions": [{"titleId":"aa0e8400-e29b-41d4-a716-446655440000","country":"Japan","memberCount":4}]}'
curl -X PUT https://nametoavatar.com/api/v1/company-roster-templates/{id} \
-H "Content-Type: application/json" \
-d '{"expectedVersion": 1, "name": "Engineering team", "positions": [{"titleId":"{titleId}","country":"Japan","memberCount":4}]}'
curl -X DELETE https://nametoavatar.com/api/v1/company-roster-templates/{id}
curl https://nametoavatar.com/api/v1/company-roster-templates/{id}/versions
curl https://nametoavatar.com/api/v1/company-roster-templates/{id}/versions/1
curl "https://nametoavatar.com/api/v1/company-rosters?pageSize=5"
curl https://nametoavatar.com/api/v1/company-rosters/{id}
curl -X POST https://nametoavatar.com/api/v1/company-rosters \
-H "Content-Type: application/json" \
-d '{"templateId": "{templateId}", "version": 1, "name": "Northstar engineering", "visibility": "private", "country": "Japan", "gender": "female", "style": "professional", "age": "adult"}'
curl -X POST https://nametoavatar.com/api/v1/company-rosters/summaries \
-H "Content-Type: application/json" \
-d '{"ids": ["661f9500-f39c-52e5-b827-557766550000"]}'
curl -X POST https://nametoavatar.com/api/v1/company-rosters/{id}/start
curl -X POST https://nametoavatar.com/api/v1/company-rosters/{id}/retry
curl -X POST https://nametoavatar.com/api/v1/company-rosters/{id}/resume
curl -X PUT https://nametoavatar.com/api/v1/company-rosters/{id}/discard \
-H "Content-Type: application/json" \
-d '{"memberId": "{memberId}"}'
curl https://nametoavatar.com/api/v1/companies
curl https://nametoavatar.com/api/v1/countries
curl https://nametoavatar.com/api/v1/languages
curl https://nametoavatar.com/api/v1/locations
curl https://nametoavatar.com/api/v1/product-categories
{
  "error": "Invalid request body."
}
{
  "error": "Authentication is required."
}
{
  "error": "Your credit balance is too low for this generation."
}
{
  "error": "Not authorized"
}
{
  "error": "Not found"
}
{
  "error": "Too many requests for this endpoint. Please try again later."
}
{
  "error": "Something went wrong. Please try again later."
}
Name to Avatar

Product

AvatarsName GeneratorAvatar GeneratorIdentity Generator

Developers

API DocsMCP Server

Resources

BlogPrivacy PolicyTerms of Service

Contact

Customer Support@kapxapot

Projects

Stay UpMapfolksTimezonedBrightwood StoriesQR LifeKarina Azatyan Photography

All rights reserved. © 2026 Name to Avatar

Created by Sergey Atroshchenko

Domain Rating by Ahrefs for nametoavatar.com