Quick Start - Zoice Documentation

Welcome to Zoice Developer Platform

Zoice Dev provides high-performance, developer-friendly APIs to generate realistic AI avatar videos, human-grade text-to-speech audio, and custom image variations.

1. Get your API Key

To get started, you will need a Zoice developer account and an API Key:

Visit the Zoice Dev Console.
Log in or create a new account by clicking Get Started.
Generate or copy your API Key from the developer dashboard. Keep this key secure.

2. Authentication

All requests to Zoice APIs require authorization. Add the following header to your API requests:

Authorization: Bearer <YOUR_ZOICE_API_KEY>

3. Generate Your First AI Avatar Video

Because video rendering is resource-intensive, generations are handled asynchronously using a fast queue system.

Step 1: Send the Generation Request

You can submit a request using either Profile IDs (existing avatar/voice profiles on your dashboard) or directly with Media URLs (custom images/vocal audio files). Submit a POST request to https://api.zoice.com/v1/run/zoice/avatar-x.

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

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

Step 2: Get the Request ID

The request returns immediately with a request_id and a processing status:

{
  "request_id": "d1f47b9c-6387-49d0-a403-85fbd9dcf1b7",
  "status": "processing"
}

Step 3: Poll for Output

Send a GET request to https://api.zoice.com/v1/fetch/{request_id} to check the task status:

Polling Request

curl -X GET "https://api.zoice.com/v1/fetch/d1f47b9c-6387-49d0-a403-85fbd9dcf1b7" \
  -H "Authorization: Bearer $ZOICE_API_KEY"

Once the generation is ready, you will receive a success status with the final video URL:

Polling Response

{
  "status": "success",
  "request_id": "d1f47b9c-6387-49d0-a403-85fbd9dcf1b7",
  "type": "video",
  "output": {
    "credits": 909,
    "result": "https://assets.zoice.com/generated/job-output-video.mp4"
  }
}

4. Request Schema (`zoice/avatar-x`)

Input Parameters

Parameter	Type	Required	Description
`avatar_id`	`string`	No	ID of the desired avatar profile character.
`avatar_image_url`	`string`	No	URL of an existing image of the selected avatar profile.
`input_image_url`	`string`	No	Direct URL to an image featuring the desired person/character.
`voice_id`	`string`	No	ID of the desired voice profile.
`script_text`	`string`	No	Text to speak using the selected voice profile.
`input_voice_url`	`string`	No	Direct URL to a vocal audio file (`.mp3` or `.wav`).
`action_prompt`	`string`	No	Description influencing facial actions/emotions (e.g., “Person is feeling excited”).
`aspect_ratio`	`string`	No	Output video aspect ratio (e.g., `9:16`, `16:9`, `1:1`). Default is `9:16`.
`resolution`	`string`	No	Video resolution quality (e.g., `720p`, `1080p`, `4k`). Default is `1080p`.

5. Other Zoice Models

Avatar Editor (`zoice/avatar-edit`)

Generate image variations of a specific avatar.

Endpoint: POST https://api.zoice.com/v1/run/zoice/avatar-edit
Request Payload:

{
  "avatar_id": "ad4ed5d7-22eb-4939-8ee2-a16fbd9dcf1b",
  "prompt": "wearing professional suit, studio lighting",
  "aspect_ratio": "16:9"
}

Speech Generator (`zoice/speech`)

Generate premium, human-grade text-to-speech audio.

Endpoint: POST https://api.zoice.com/v1/run/zoice/speech
Request Payload:

{
  "voice_id": "a737e319-8b5b-43e8-a189-c45fcd9def3a",
  "text": "Welcome to the future of synthetic media.",
  "speed": 1.0
}

Reusable Avatar Profile (`zoice/avatar-profile`)

Endpoint: POST https://api.zoice.com/v1/run/zoice/avatar-profile
Request Payload:

{
  "name": "Sarah Business Presenter",
  "base_image_url": "https://example.com/sarah-photo.jpg",
  "pose": "standing"
}

Reusable Voice Profile (`zoice/voice-profile`)

Endpoint: POST https://api.zoice.com/v1/run/zoice/voice-profile
Request Payload:

{
  "voice_name": "Custom Corporate Voice",
  "sample_audio_url": "https://example.com/corporate-voice-sample.mp3"
}

​Welcome to Zoice Developer Platform

​1. Get your API Key

​2. Authentication

​3. Generate Your First AI Avatar Video

​Step 1: Send the Generation Request

​Step 2: Get the Request ID

​Step 3: Poll for Output

​4. Request Schema (zoice/avatar-x)

​Input Parameters

​5. Other Zoice Models

​Avatar Editor (zoice/avatar-edit)

​Speech Generator (zoice/speech)

​Reusable Avatar Profile (zoice/avatar-profile)

​Reusable Voice Profile (zoice/voice-profile)