Zoice For Developers | Zoice API

Update Avatar Profile API Docs

The PATCH /v1/avatar-profiles/{avatar_id} updates an existing avatar profile with the given avatar_id value (passed as the path parameter). Only the fields provided in the request body will be updated, allowing for partial updates without affecting the other configurations. The updatable fields include avatar_name, gender, age, ethnicity, and description.

API Request

Sending Request

bash

curl -X PATCH "https://api.zoice.com/v1/avatar-profiles/b92d8dd4-f3fa-4624..." \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOICE_API_KEY" \
  -d '{
    "avatar_name": "George",
	"gender": "male",
    "age": "senior",
    "ethnicity": "white",
    "description": "A distinguished senior gentleman whose warm, wise expression conveys trust, authority, and years of experience."
  }'

Response Format

json

{
  "status": "success",
  "avatar": {
    "avatar_id": "a0c35e43-9050-...",
    "avatar_name": "George",
    "description": "A distinguished senior gentleman whose warm, wise expression conveys trust, authority, and years of experience.",
    "age": "senior",
    "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"
  }
}

Schemas

Input

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

Body Parameter	Type	Required	Default	Range
avatar_name	string	No	-	-
gender	string	No	-	`male`, `female`, `other`
age	string	No	-	`child`, `teen`, `young-adult`, `early-middle-aged`, `late-middle-aged`, `senior`
ethnicity	string	No	-	`"white"`, `"black"`, `"east-asian"`, `"southeast-asian"`, `"south-asian"`, `"middle-eastern"`, `"pacific-islander"`, `"hispanic-or-latino"`
description	string	No	-	-

Output

Field	Type	Description
status	string	The status of the API request. enums: `"success"`, `"processing"`, `"failed"`
avatar	object	An object containing metadata of the updated 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.