zoice/avatar-profile API Docs

Zoice 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 heavy media rendering tasks 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/run/zoice/avatar-profile" \
  -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

typescript

{
  "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": [
      {
        "status": "success",
        "image_url": "https://storage.zoice.com/api/assets/image-841c3adc...png",
        "createdAt": "2026-07-18T07:56:50.556Z",
        "generation_info": {
          "image_prompt": "Photorealistic portrait of a white woman...",
          "resolution": "2k",
          "aspect_ratio": "1:1"
        }
      }
    ],
    "generation_info": {
      "base_image_prompt": "Photorealistic portrait of a white woman..."
    },
    "createdAt": "2026-07-18T07:56:17.092Z",
    "updatedAt": "2026-07-18T07:57:23.478Z",
    "base_image_url": "https://storage.zoice.com/api/assets/image-841c3adc...png",
    "featured_image_url": "https://storage.zoice.com/api/assets/image-243f8d5f...png"
  }
}

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
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)	A list of generated image objects associated with this avatar.
output.images[].image_url	string (url)	The direct storage URL for the generated image.
output.base_image_url	string (url)	The URL of the base anchor image used for the avatar.
output.featured_image_url	string (url)	The URL of the selected featured image for the profile display.