Zoice For Developers | Zoice API

Create Avatar Profile API Docs

Zoice Avatar Profile API endpoint is used to create AI avatar character profiles. These profiles can be further used to generate AI avatar videos using the zoice/avatar-x model.

API Request

The API endpoint handles the task asynchronously using a fast queue-based system, and the request immediately returns a request_id. Use the request_id to poll the status of the generation and return the result after the task is completed.

Sending Request

bash

curl -X POST "https://api.zoice.com/v1/avatar-profiles" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOICE_API_KEY" \
  -d '{
    "avatar_name": "Claire",
    "base_image_prompt": "Photorealistic portrait of a white woman in her mid-30s, confident and approachable expression, natural smile, bright eyes looking directly at the camera, healthy skin with realistic texture, shoulder-length light brown hair styled neatly, subtle natural makeup, elegant and modern appearance.",
	"gender": "female",
	"age": "young-adult",
	"ethnicity": "white",
	"description": "young adult white woman"
}'

Response Format

json

{
  "request_id": 'd1f47b9c-6387-49d0-a403-...',
  "status": 'processing',
}

Polling and Output

After submitting an asynchronous API request, you can use the request_id obtained from the response to further poll for the status of the generation and ultimately retrieve the result after the completion. Use the /v1/fetch/request_id endpoint to perform this operation.

Polling Request

bash

curl -X GET "https://api.zoice.com/v1/fetch/{request_id}" \
  -H "Authorization: Bearer $ZOICE_API_KEY"

Polling Response

json

{
  "status": "success",
  "request_id": "9c62331d-9c1d-4c23...",
  "type": "avatar_profile",
  "output": {
	"credits": 16,
    "avatar_id": "cb5ef0af-6a22-4c9a...",
    "avatar_name": "Claire",
    "description": "young adult white woman",
    "age": "young-adult",
    "gender": "female",
    "ethnicity": "white",
    "images": [
      {
        "image_id": "e465047b-d1ce-...",
        "image_url": "https://storage.zoice.com/api/assets/image-841c3adc...png",
        "generation_info": {
          "image_prompt": "Photorealistic portrait of a white woman...",
          "resolution": "2k",
          "aspect_ratio": "1:1"
        },
		"created_at": "2026-07-18T07:56:50.556Z",
      }
    ],
    "generation_info": {
      "base_image_prompt": "Photorealistic portrait of a white woman..."
	  "resolution": "2k",
      "aspect_ratio": "1:1",
    },
	"avatar_type": "private",
    "avatar_state": "active",
	"base_image_id": "e465047b-d1ce-...",
    "base_image_url": "https://storage.zoice.com/api/assets/image-841c3adc...png",
    "featured_image_url": "https://storage.zoice.com/api/assets/image-243f8d5f...png",
	"created_at": "2026-07-18T07:56:17.092Z",
  }
}

Schema

Input

Parameter	Type	Required	Default	Range	Description
avatar_name	string	Yes	-	-	Name to be assigned to avatar profile
base_image_prompt	string	No	-	-	Prompt including the physical traits of the avatar character to be generated
reference_image_urls	string[]	No	-	-	An optional array of image URLs to be used as references along with `base_image_prompt`.
base_image_url	string	No	-	-	Alternative to prompt text; add an image url directly to be used as base image for the avatar profile
gender	string	No	-	`"male"`, `"female"`, `"other"`	The gender for 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
description	string	No	-	-	Short description about the avatar profile

Output

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