Zoice For Developers | Zoice API

Get Avatar Profile API Docs

The GET /v1/avatar-profiles/{avatar_id} is the endpoint to use to receive the metadata regarding a single avatar profile with the given avatar_id.

API Request

Replace the avatar_id placeholder in the /v1/avatar-profiles/{avatar_id} endpoint with its value to get information regarding an avatar. The List All Avatars helper endpoint may come in handy if you'd like to see all avatar profiles and their avatar_id values available to your account.

Sending Request

bash

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

Response Format

json

{
  "status": "success",
  "avatar": {
    "avatar_id": "a0c35e43-9050-...",
    "avatar_name": "Ethan Miller",
    "description": "Middle aged man for commercials",
    "age": "early-middle-aged",
    "gender": "male",
    "ethnicity": "white",
    "images": [
      {
        "image_id": "739dadb1-fb95-...",
        "image_url": "https://storage.zoice.com/api/assets/image-d2535a30-...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-...png",
    "featured_image_url": "https://storage.zoice.com/api/assets/image-8c11ef57-...png",
    "created_at": "2026-09-11T18:50:45.794Z"
  }
}

Schema

Input

Path Parameter	Type	Required	Default	Range
avatar_id	string	Yes	-	a valid UUID string

Output

Field	Type	Description
status	string	The status of the API request. enums: `"success"`, `"processing"`, `"failed"`
avatar	object	An object containing metadata of the avatar profile. Refer polling response above.
avatar.avatar_id	string (uuid)	The unique identifier for the generated avatar profile.
avatar.avatar_name	string	The name assigned to the avatar.
avatar.description	string	A brief description of the avatar's characteristics.
avatar.age	string	The age category of the avatar. enums: `"child"`, `"teen"`, `"young-adult"`, `"early-middle-aged"`, `"late-middle-aged"`, `"senior"`
avatar.gender	string	The gender of the avatar. enums: `"male"`, `"female"`, `"other"`
avatar.ethnicity	string	The ethnicity of the avatar. enums: `"white"`, `"black"`, `"east-asian"`, `"southeast-asian"`, `"south-asian"`, `"middle-eastern"`, `"pacific-islander"`, `"hispanic-or-latino"`
avatar.images	array (object)	An array of generated image objects associated with this avatar.
avatar.images[].image_id	string	The unique identifier for the image object.
avatar.images[].image_url	string (url)	The direct storage URL for the generated or uploaded image.
avatar.images[].generation_info	object	The object containing the information regarding image generation.
avatar.images[].generation_info.image_prompt	string	The text prompt used for the image generation.
avatar.images[].generation_info.resolution	string	The resolution set for the image generation, for eg., `"2k"`.
avatar.images[].generation_info.aspect_ratio	string	The aspect ratio set for the image generation, for eg., `"1:1"`.
avatar.images[].generation_info.reference_image_urls	string[]	The optional array of image URLs used as references for image generation.
avatar.images[].generation_info.image_url	string	The original source URL to the image in case of direct image upload.
avatar.images[].created_at	string	Date and time of creation in UTC format of the image generation.
avatar.avatar_type	string	The visibility type of the avatar profile. enums: `"private"`, `"public"`
avatar.avatar_state	string	The current state of the avatar profile. enums: `"active"`, `"processing"`
avatar.base_image_id	string	The unique identifier of the current base image of the avatar profile.
avatar.base_image_url	string (url)	The URL of the base image of the avatar.
avatar.featured_image_url	string (url)	The URL of the featured image of the avatar.
avatar.created_at	string	Date and time of creation in UTC format of the avatar profile.