heygen-avatar-v Prompt Recipes: Copy-Paste Prompts With Real Outputs

Most "prompt guide" posts for talking-avatar APIs show you a screenshot and ask you to trust it. This one doesn't. Every video embedded below was actually rendered through the hiapi heygen-avatar-v endpoint — same model, same account, same /v1/tasks call you'll make yourself. You get the exact JSON payload next to each clip, so you can copy it, swap two or three fields, and get your own version out the door in minutes.

heygen-avatar-v turns a script (or an audio file) into a talking avatar video: pick a preset avatar, pick a voice, and the model handles lip-sync, framing, and delivery. It bills per second of rendered output — $0.15/s — so there's no separate "credits" system to learn, just the JSON below.

Recipe 1: the clean product/pricing explainer

This is the "talking head in an office, explaining something simple" pattern — the most common ask for support docs, pricing pages, and onboarding emails.

VIDEO

Exact payload used to render the clip above:

{
  "model": "heygen-avatar-v",
  "input": {
    "prompt": "Heres the pricing breakdown you asked for, explained simply.",
    "avatar": "Brandon Business Standing Front",
    "voice": "Jack Sterling - Broadcaster",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "background": { "type": "color", "value": "#0F172A" },
    "caption": false,
    "output_format": "mp4"
  }
}

Copy this and only change one thing to start: the prompt string. Everything else — avatar, voice, framing — is a solid default for a landing-page or FAQ-style clip.

Field-by-field:

• prompt — the script the avatar speaks. This is the one required field (or use audio_url instead — see the reproduction walkthrough below).
• avatar — a named preset from a large enum (hundreds of options). Brandon Business Standing Front is a filmed, standing, front-facing business avatar.
• voice — also a named preset. Jack Sterling - Broadcaster is a deeper, formal narration voice that pairs well with business/explainer copy.
• aspect_ratio — 16:9, 9:16, 4:5, 5:4, 1:1, or auto.
• resolution — 720p, 1080p, or 4k.
• caption — boolean. false here; see Recipe 2 for what true actually does.
• output_format — mp4 or webm (the model supports transparent WebM output for overlay use cases).

The gotcha worth knowing before you burn a render on it: notice the background field above is set to a navy color override — and if you watch the clip, the background is still the avatar's original filmed office, not navy. That's not a payload mistake. background (an object shaped { "type": "color" | "image", "value": ... }) works correctly for illustrated/rendered avatars, but filmed presets like Brandon Business Standing Front are real video footage of a person in a real room — there's no background layer to swap, because the backdrop is baked into the source footage. If you need a custom background, pick an illustrated/green-screen-style avatar preset instead of a filmed one; don't spend a render finding this out the way we did.

Recipe 2: the vertical social hook with captions

Same model, completely different output shape — this one targets Reels/TikTok/Shorts: vertical framing, a casual avatar, and burned-in-adjacent captions.

VIDEO

Exact payload used to render the clip above:

{
  "model": "heygen-avatar-v",
  "input": {
    "prompt": "New drop just landed, swipe up and shop now!",
    "avatar": "Riley Casual Front",
    "voice": "Cute Chloe - Friendly",
    "aspect_ratio": "9:16",
    "resolution": "1080p",
    "caption": true,
    "output_format": "mp4"
  }
}

Two differences from Recipe 1 that do all the work here:

• aspect_ratio: "9:16" — vertical framing, no other field needs to change for the model to reframe the shot correctly.
• caption: true — this does not burn captions into the video pixels. It generates a separate .srt sidecar file alongside the .mp4, which your player/editor overlays. If you need captions literally baked into the frame, add them yourself in post — don't expect caption: true alone to produce hard-subs.

Riley Casual Front + Cute Chloe - Friendly is a lighter, younger-energy pairing than Recipe 1's avatar/voice combo — a useful default whenever the brief says "casual" or "social" instead of "corporate."

Reproducing this yourself: the full /v1/tasks flow

heygen-avatar-v runs on hiapi's async task API, same pattern as every other video model on the platform: create a task, poll it, download the result.

1. Create the task

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-v",
    "input": {
      "prompt": "Your script goes here.",
      "avatar": "Brandon Business Standing Front",
      "voice": "Jack Sterling - Broadcaster",
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "output_format": "mp4"
    }
  }'

This returns a taskId. One thing to know before you write this call: prompt and audio_url are mutually exclusive and exactly one is required. Send neither, or both, and you'll get this back immediately (no task, no charge):

invalid input: input: exactly one of prompt or audio_url is required

Use audio_url instead of prompt if you already have a voiceover recorded (a different language dub, a client-approved VO take, etc.) and just want the avatar to lip-sync to it.

2. Poll until it's done

curl -s https://api.hiapi.ai/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Status moves through handling → archiving → success (or failed). Poll every few seconds — a render like the two above takes roughly 15–20 seconds per second of output.

3. Download the output

On success, the response includes an output array; grab output[0].url and download it immediately — the URL carries an expireAt timestamp and isn't meant to be linked to long-term. Move the bytes to your own storage before you do anything else with them.

What it costs

heygen-avatar-v bills per second of rendered output at a flat rate — there's no separate charge for resolution, aspect ratio, or captions.

There's no duration field to set — length comes entirely from how long your prompt script (or audio_url file) takes to read aloud. Tighter scripts render cheaper and faster; that's the main lever you have on cost.

More recipes to adapt (not rendered here — build these yourself)

The two clips above are real outputs so you can trust the field values. The four below are prompt patterns worth trying — write your own script for each and reuse the avatar/voice/format choices as a starting point:

• Onboarding walkthrough (16:9, 1080p): pair a calm, professional avatar/voice combo like Recipe 1's with a step-by-step script ("First, click Settings. Then...") and caption: false — let your product UI do the visual work in a screen-recording overlay.
• FAQ answer clip (1:1 or 4:5, 720p is enough): one question, one answer, under 15 seconds. Cheap to render at $0.15/s, and a stack of these embedded on a support page beats one long video nobody finishes.
• Multi-language dub via audio_url: record (or generate) a voiceover in the target language, pass it as audio_url instead of prompt, and let the avatar lip-sync to it — useful when you already have translated VO and just need a visual presenter.
• Webinar/event reminder (9:16, caption: true): Recipe 2's casual pairing plus a countdown-style script ("Three days left to register...") — the .srt sidecar means you can localize captions separately from re-rendering the video.

FAQ

Does background ever work, or should I just ignore it? It works — just not on filmed/live-action avatar presets, for the reason explained in Recipe 1. If your brief needs a custom background, choose an illustrated or studio/green-screen-style avatar preset rather than a "filmed in an office" one, and the { "type": "color" | "image", "value": ... } override will apply as expected.

Can I control exactly how long the output video is? Not directly — there's no duration parameter. Length is driven by your script (via prompt) or your audio file's length (via audio_url). To hit a target length, edit the script, not the request.

What's the difference between caption: true and burning subtitles into the video? caption: true produces a .srt file next to your .mp4, not hardcoded text in the frame. If you need hard-subs, overlay them yourself after downloading the output — see the "vertical social hook" recipe above.

Do I need to pick a resolution and an aspect ratio, or does one imply the other? Both are independent, required-if-you-want-non-default fields: resolution (720p / 1080p / 4k) controls pixel density, aspect_ratio (16:9 / 9:16 / 4:5 / 5:4 / 1:1 / auto) controls framing/orientation. Set both explicitly rather than relying on defaults, since a mismatch between the two (say, 4k at 9:16) still renders — it just costs the same per second regardless of pixel count.

Where to go next

• Full field list and live pricing: heygen-avatar-v model page
• Compare per-second video pricing across models: hiapi pricing
• Browse other talking-avatar and video-generation models: hiapi models directory

Ready to render your own? Grab an API key from your hiapi dashboard and paste Recipe 1's payload in — it's a working request, not a placeholder.