Skywork AI Skyreels V3 Pro Multi Avatar API Documentation

Skywork AI Skyreels V3 Pro Multi Avatar API Documentation

Playground

SkyReels V3 Pro Multi Avatar is a high-quality AI talking avatar video generation model that creates multi-speaker avatar videos from one image, multiple audio tracks, and bounding boxes. Ready-to-use REST inference API for group avatar videos, digital humans, virtual presenters, dialogue scenes, education content, marketing creatives, and professional multi-avatar video workflows with simple integration, no coldstarts, and affordable pricing.

Features

Skywork AI SkyReels V3 Pro Multi Avatar generates a two-speaker avatar video from a single first-frame image plus separate left and right audio tracks. It is designed for higher-quality multi-character speaking scenes, with stronger realism, smoother facial animation, and more polished lip-sync than the Standard variant.

Why Choose This?

• Two-speaker avatar generation Animate two speakers from a single scene image with separate audio tracks for each side.

• Higher-quality multi-avatar performance The Pro variant is built for stronger realism, cleaner lip-sync, and more polished facial animation.

• Separate left and right speaker control Upload different audio clips for the left and right speakers to drive each character independently.

• Prompt-guided scene behavior Add a prompt to guide mood, scene setup, speaking style, or camera feel.

• Speaker detection control Use bboxes_type to control whether speaker detection is based on body or face.

• Production-ready workflow Suitable for conversations, interviews, presenter scenes, and other multi-character speaking video workflows.

Parameters

How to Use

1. Upload the first-frame image — provide the scene image containing the two speakers.
2. Upload left speaker audio — add the audio for the person on the left side of the image.
3. Upload right speaker audio — add the audio for the person on the right side of the image.
4. Write your prompt — describe the speaking behavior, mood, scene setup, or camera style.
5. Choose speaker detection type (optional) — use body or face depending on how you want the model to identify each speaker.
6. Submit — run the model and download the generated video.

Example Prompt

Let the two speakers talk naturally in a professional office setting, with subtle head movement, realistic facial expressions, and stable identity for both people.

Pricing

Pricing is based on the combined duration of both audio tracks.

Billing Rules

• Base price is $0.12 per second
• Total billed duration = left audio duration + right audio duration
• Total price = $0.12 × (left audio duration + right audio duration)
• prompt, first_frame_image, and bboxes_type do not affect pricing

Example Costs

Best Use Cases

• Two-person conversations — Create dialogue scenes with separate speaking control for each person.
• Interview videos — Animate interviewer and guest from a single scene image.
• Presenter pairs — Generate two-host explainer or announcement videos.
• Character conversations — Build short dialogue clips for storytelling or social content.
• Virtual spokesperson scenes — Create multi-speaker brand or business communication videos.

Pro Tips

• Use a clear image where the left and right speakers are visually distinct.
• Upload clean audio for both sides to improve lip-sync and speaking clarity.
• Use face when facial positioning is more reliable than full-body placement.
• Use body when the characters are farther from the camera or their full pose matters.
• Keep the prompt simple and focused on speaking behavior, mood, or scene intent.
• Make sure the left and right audio assignments match the actual positions of the people in the image.

Notes

• prompt, first_frame_image, left_audio, and right_audio are required.
• bboxes_type defaults to body.
• Pricing depends on the sum of both audio durations.
• This workflow is intended for two-speaker avatar video generation from a single scene image.

Related Models

• Skywork AI SkyReels V3 Pro Single Avatar — Higher-quality single-avatar speaking video generation.
• Skywork AI SkyReels V3 Standard Multi Avatar — Standard multi-avatar workflow at a lower price point.
• Skywork AI SkyReels V3 Standard Single Avatar — Standard single-avatar talking video generation.
• Skywork AI SkyReels V3 Reference-to-Video — Generate videos from one or more reference images and a prompt.

Duration limit

The maximum supported audio duration is 200 seconds per track. Longer audio is automatically trimmed to 200 seconds before processing.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "first_frame_image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "left_audio": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
  "right_audio": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
  "bboxes_type": "body"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/skywork-ai/skyreels-v3-pro/multi-avatar" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL=$(printf '%s' "${TASK}" | jq -r '.urls.get // empty')
if [ -z "${RESULT_URL}" ]; then RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"; fi

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    created|processing) sleep 2 ;;
    *) printf 'Unexpected status: %s
' "${STATUS}" >&2; exit 1 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters