Zoice For Developers | Zoice API

List Avatar Profiles API Docs

List Avatar Profiles API helper endpoint lets you get a paginated response of all avatars available to your account.

API Request

Sending a GET request to the endpoint immediately returns a status along with a paginated list of avatar profiles on success. The paginated result uses a default limit of 10 and the response adds a has_more field if there are more pages and a next_page_token field to query the next page.

Sending Request without Query Params

Simply sending a GET request to the endpoint without any query parameters returns up to 10 most recent avatar profile records.

bash

curl -X GET "https://api.zoice.com/v1/avatar-profiles" \
  -H "Authorization: Bearer $ZOICE_API_KEY"

Sending Request with Query Params

The /v1/avatar-profiles endpoint accepts optional gender, age, ethnicity, page_size and next_page_token query parameters to filter the responses based on your requirements.

bash

curl -X GET "https://api.zoice.com/v1/avatar-profiles?gender=male&age=young-adult" \
  -H "Authorization: Bearer $ZOICE_API_KEY"

Response Format

A successful request will return a JSON object with fields including status, avatars, has_more, next_page_token.

json

{
  "status": "success",
  "avatars": [
    {
      "avatar_id": "a0c35e43-9050-...",
      "avatar_name": "Ethan Miller",
      "description": "An early middle-aged man in his late 30s to mid-40s",
      "age": "early-middle-aged",
      "gender": "male",
      "ethnicity": "white",
      "images": [
        {
          "image_id": "739dadb1-fb95-...",
          "image_url": "https://storage.zoice.com/api/assets/image-d2535a30-aae1-...png",
          "generation_info": {
            "image_prompt": "Create a highly realistic portrait avatar of a confident, friendly man living in the countryside...",
            "resolution": "2k",
            "aspect_ratio": "1:1"
          },
          "created_at": "2026-09-11T18:51:23.840Z"
        }
      ],
      "generation_info": {
        "base_image_prompt": "Create a highly realistic portrait avatar of a confident, friendly man living in the countryside...",
        "resolution": "2k",
        "aspect_ratio": "1:1"
      },
      "avatar_type": "private",
      "avatar_state": "active",
      "base_image_id": "739dadb1-fb95-...",
      "base_image_url": "https://storage.zoice.com/api/assets/image-d2535a30-aae1-...png",
      "featured_image_url": "https://storage.zoice.com/api/assets/image-8c11ef57-...png",
      "created_at": "2026-09-11T18:50:45.794Z"
    },
	{
      "avatar_id": "8eb462a4-4be6-4186-...",
      "avatar_name": "Jason",
      "description": "Jason is a confident, approachable man with a polished and professional appearance.",
      "age": "early-middle-aged",
      "gender": "male",
      "ethnicity": "white",
      "images": [
        {
          "image_id": "92d3371d-42d7-...",
          "image_url": "https://storage.zoice.com/api/backup-assets/image-0a171b7a-cd53-...jpeg",
          "generation_info": {
            "base_image_url": "https://images.pexels.com/photos/15396621...jpeg"
          },
          "created_at": "2026-09-12T11:40:38.104Z"
        }
      ],
      "avatar_type": "private",
      "avatar_state": "active",
      "base_image_id": "92d3371d-42d7-...",
      "base_image_url": "https://storage.zoice.com/api/backup-assets/image-0a171b7a-cd53-...jpeg",
      "featured_image_url": "https://storage.zoice.com/api/assets/image-9996a421-...png",
      "generation_info": {
        "base_image_url": "https://images.pexels.com/photos/15396621...jpeg"
      },
      "created_at": "2026-09-12T11:40:21.436Z"
    },
  ],
  "has_more": false,
  "next_page_token": null
}

Handling Pagination

The paginated result uses a default limit of 10 and this can be changed by using the page_size query parameter.

The response adds a has_more field if there are more pages and a next_page_token field to query the next page.

If has_more value is true, include the next_page_token value in the query parameter when you send a request next time to fetch additional pages of results.

Schema

Input

Query Parameter	Type	Required	Default	Range	Description
gender	string	No	-	`male`, `female`, `other`	The gender of the avatar profile.
age	string	No	-	`child`, `teen`, `young-adult`, `early-middle-aged`, `late-middle-aged`, `senior`	The age group of the avatar profile.
ethnicity	string	No	-	`"white"`, `"black"`, `"east-asian"`, `"southeast-asian"`, `"south-asian"`, `"middle-eastern"`, `"pacific-islander"`, `"hispanic-or-latino"`	The ethnicity of the avatar profile.
page_size	integer	No	10	1..100	Number of records to be included in a single response.
next_page_token	string	No	-	-	The value to fetch additional pages of results.

Output

Field	Type	Description
status	string	The status of the API request. Allowed values: `"success"`, `"processing"`, `"failed"`
avatars	object[]	Array containing available avatar profile objects.
avatars[].avatar_id	string (uuid)	Unique identifier for the avatar profile.
avatars[].avatar_name	string	Display name of the avatar profile.
avatars[].description	string	The description of the avatar profile.
avatars[].age	string	The age of the avatar profile. Allowed values: `child`, `teen`, `young-adult`, `early-middle-aged`, `late-middle-aged`, `senior`
avatars[].gender	string	The gender of the avatar. Allowed values: `"male"`, `"female"`, `"other"`
avatars[].avatar_type	string	The type of the avatar. Allowed values: `"private"`, `"imported"`, `"public"`
avatars[].avatar_state	string	The current state of the avatar. Allowed values: `"active"`, `"processing"`
avatars[].images	object[]	An array of generated image objects associated with this avatar.
avatars[].images[].image_id	string	The unique identifier for the image object.
avatars[].images[].image_url	string (url)	The direct storage URL for the generated or uploaded image.
avatars[].images[].generation_info	object	The object containing the generation information of image.
avatars[].images[].generation_info.image_prompt	string	The text prompt used for the image generation.
avatars[].images[].generation_info.resolution	string	The resolution set for the image generation, for eg., `"2k"`.
avatars[].images[].generation_info.aspect_ratio	string	The aspect ratio set for the image generation, for eg., `"1:1"`.
avatars[].images[].generation_info.reference_image_urls	string[]	The optional array of image URLs used as references for image generation.
avatars[].images[].generation_info.image_url	string	The original source URL to the image in case of direct image upload.
avatars[].images[].created_at	string	Date and time of creation in UTC format of the image.
avatars[].base_image_id	string	The unique identifier of the current base image of the avatar profile.
avatars[].base_image_url	string (url)	The URL of the base image of the avatar.
avatars[].featured_image_url	string (url)	The URL of the featured image of the avatar.
avatars[].created_at	string	Date and time of creation in UTC format of the avatar profile.
has_more	boolean	The flag indicating whether more pages are available to query. Allowed values: `true`, `false`
next_page_token	string \| null	A string ID that can be passed as `next_page_token` in request to get the next page of avatars.