Make a talking avatar video with the Percify API

Build a talking avatar video through the Percify API in three calls: gpt-image-2 for the face, zonos2 for the cloned voice, infinitetalk for lip-sync.

The Percify API makes a talking avatar video in three generations: an image model creates the face, a voice model speaks your script in a cloned voice, and a lip-sync model animates the face to that audio. Each step is a POST /v1/run, and each output URL is the input of the next. You can skip the first two steps if you already have a portrait photo or a finished voiceover.

Step	Model id	Input	Output
1. Face	gpt-image-2	prompt	Image URL
2. Voice	zonos2	text + audio (a sample of the voice to clone)	Audio URL
3. Video	infinitetalk-fast or infinitetalk	image + audio	Video URL

What you need

• A Percify API key (Scale or Ultra plan). See Authentication.
• For step 2, a short, clean speech recording of the voice to clone, at a public https URL, as .mp3 or .wav. Only clone a voice you have permission to use.
• Or skip steps 1 and 2 with your own portrait (.jpg or .png with a clearly visible face) and your own voiceover (.mp3 or .wav), both at public https URLs.

Run the pipeline

Node.js

const API = "https://api.percify.io/v3/playground/v1";
const headers = {
  Authorization: `Bearer ${process.env.PERCIFY_API_TOKEN}`,
  "Content-Type": "application/json",
};

async function generate(modelId, input, key) {
  let res = await fetch(`${API}/run`, {
    method: "POST",
    headers: { ...headers, "Idempotency-Key": key },
    body: JSON.stringify({ modelId, input }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(typeof body === "string" ? body : body.message);
  let data = body.data;
  while (data.status !== "succeeded" && data.status !== "failed") {
    res = await fetch(`${API}/generations/${data.id}?wait=45`, { headers });
    ({ data } = await res.json());
  }
  if (data.status === "failed") throw new Error(data.error);
  return data.output.urls[0];
}

// 1. Face
const image = await generate("gpt-image-2", {
  prompt: "Head-and-shoulders photo of a friendly presenter facing the camera, soft studio light, plain background",
  aspect_ratio: "2:3",
}, "episode-12-face");

// 2. Voice
const audio = await generate("zonos2", {
  text: "Welcome back. Today I will show you how we cut our onboarding time in half.",
  audio: "https://example.com/my-voice-sample.wav",
}, "episode-12-voice");

// 3. Video
const video = await generate("infinitetalk-fast", { image, audio }, "episode-12-video");
console.log(video);

The idempotency keys make the script safe to rerun: a step that already ran returns its existing generation instead of charging again.

How much does a talking avatar video cost?

Each step is charged separately, from your plan’s credits:

Step	How it is billed
gpt-image-2	Per image. The quality input changes the price.
zonos2	By the length of the voice sample you pass in audio.
infinitetalk-fast, infinitetalk	Per second of the audio. On infinitetalk, 720p costs twice as much as 480p.

Get exact numbers before you run: call POST /v1/estimate for each step with the inputs you plan to send. For step 3, estimate with a real audio URL, because Percify prices it from the audio’s length.

Tips for better results

• Frame the portrait the way you want the video. The video keeps the input image’s aspect ratio, so crop it first.
• One face, facing the camera. A clear, front-facing face gives the lip-sync model the most to work with.
• Reuse the voice. There is no saved voice id in the REST API: send the same sample URL to zonos2 each time to keep a consistent voice.
• Start with infinitetalk-fast while you test scripts, then switch to infinitetalk at 720p for final renders.
• Long scripts take longer. Use ?wait=45 in a loop or a webhook instead of a tight poll.

AI agents can do all three steps for you. Through the MCP server, create_avatar saves a face and a voice once, and avatar_say makes that avatar speak any script.

Related

Lip-sync video (InfiniteTalk)

Every input of step 3.

Voice cloning and speech

zonos2 and the text to speech models.

Estimate cost

Price each step before running it.

Lip-sync in the app

The same models without code.