Zoice For Developers | Zoice API

Avatar Videos API Docs

Zoice Avatar Videos endpoint, available through POST /v1/avatar-videos, can be used to generate ultra-realistic AI avatar videos, combining human-grade audio synthesis and natural body movements. It supports resolution of up to 4K and a wide range of aspect ratio options including 1:1, 9:16, 16:9 and more. This endpoint uses Zoice's premier zoice/avatar-x model as the video generation engine.

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 Using Profile ID's

bash

curl -X POST "https://api.zoice.com/v1/avatar-videos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOICE_API_KEY" \
  -d '{
  	"model": "zoice/avatar-x",
    "avatar_id": "ad4ed5d7-22eb-4939-8ee2-...",
    "image_id": "img_67ab890....",
	"voice_model": "elevenlabs/eleven_v3",
    "voice_id": "a737e319-8b5b-43e8-a189-...",
    "script_text": "Hi, this is my digital avatar talking!",
	"action_prompt": "Person is feeling excited.",
    "aspect_ratio": "9:16",
    "resolution": "1080p"
}'

Sending Request Using Media URL's

bash

curl -X POST "https://api.zoice.com/v1/avatar-videos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOICE_API_KEY" \
  -d '{
  	"model": "zoice/avatar-x",
    "input_image_url": "https://assets.zoice.com/......png",
    "input_voice_url": "https://assets.zoice.com/......mp3",
	"enhance_audio": true,
    "action_prompt": "Person is feeling excited.",
    "aspect_ratio": "9:16",
    "resolution": "1080p"
}'

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": 'd1f47b9c-6387-49d0-a403-...',
  "type": "video",
  "output": {
    "credits": 909,
    "result": "https://assets.zoice.com/..."
  }
}

Schema

Input

Parameter	Type	Required	Default	Range	Description
model	string	No	`zoice/avatar-x`	`zoice/avatar-x`	Model to use for avatar video generation.
avatar_id	string	No	-	-	Avatar ID of the desired avatar profile
image_id	string	No	-	-	Image ID of one of the existing images of the select avatar
input_image_url	string	No	-	-	Image url featuring the desired person
voice_id	string	No	-	-	Voice ID of the desired voice profile
voice_model	string	No	`elevenlabs/eleven_v3`	`elevenlabs/eleven_v3`, `elevenlabs/eleven_v3_conversational`, `elevenlabs/eleven_multilingual_v2`, `elevenlabs/eleven_flash_v2_5`	AI model to use for audio generation. Keep it null if unsure.
script_text	string	No	-	-	Text to speech to be generated with the select voice profile
input_voice_url	string	No	-	-	Direct audio url featuring the audio
action_prompt	string	No	-	-	Influences the action of the character in video
aspect_ratio	string	No	1:1	`"1:1"`, `"2:3"`, `"3:2"`, `"3:4"`, `"4:3"`, `"4:5"`, `"5:4"`, `"9:16"`, `"16:9"`, `"21:9"`	Aspect ratio of the video
resolution	string	No	480p	`"480p"`, `"720p"`, `"1080p"`, `"2k"`, `"4k"`	Resolution of the video

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.
output.credits	number	Credits used for generation.
output.result	string (url)	The secure HTTP URL where the generated asset can be downloaded.