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

heygen-avatar-v turns a script or an audio file into a talking avatar video. The two recipes below include their video outputs and exact request payloads: a business explainer and a vertical product hook. Start with the explainer: Generate with this prompt →

It bills per second of rendered output at $0.15/s. Every request needs avatar and exactly one of prompt or audio_url.

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"
  }
}

Heres the pricing breakdown you asked for, explained simply.

Generate with this prompt → Select Brandon Business Standing Front, Jack Sterling - Broadcaster, 16:9, 1080p, and 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. Use exactly one of prompt or audio_url; a script can contain up to 5,000 characters.
• avatar — required; pass a preset's exact Request value. 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. For a transparent overlay, pair webm with remove_background: true and check the downloaded result.

Background behavior in this historical clip: the payload requested navy (#0F172A), while the saved video shows the office backdrop. This single result does not establish background behavior for every filmed avatar. The parameter reference supports background as { "type": "color" | "image", "value": ... } and a separate remove_background flag; choose those settings for your composition and check the result.

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 a separate subtitle file.

VIDEO

Exact payload used to render the clip above:

{
  "model": "heygen-avatar-v",
  "input": {
    "prompt": "New drop just landed: our travel mug keeps coffee hot for twelve hours. Swipe up and grab yours today!",
    "avatar": "Riley Casual Front",
    "voice": "Charming Charles - Friendly",
    "aspect_ratio": "9:16",
    "resolution": "1080p",
    "caption": true,
    "output_format": "mp4"
  }
}

The saved clip is 1080×1920 and about 6.5 seconds long.

New drop just landed: our travel mug keeps coffee hot for twelve hours. Swipe up and grab yours today!

Generate with this prompt → Select Riley Casual Front, Charming Charles - Friendly, 9:16, 1080p, captions on, and MP4. The link prefills only the script.

The key settings for this recipe:

• aspect_ratio: "9:16" — requests vertical framing; this saved clip is 1080×1920.
• 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 + Charming Charles - Friendly pairs the male avatar with a male voice for this casual product announcement.

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 --fail-with-body -sS --connect-timeout 10 --max-time 60 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"
    }
  }'

Check the HTTP status, parse the JSON, and confirm code: 200 with a nonempty data.taskId; save that ID before polling. If the POST times out or its response cannot be validated, check your task records before submitting again. avatar is required, and prompt and audio_url are mutually exclusive and exactly one is required. Sending neither or both fails input validation:

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 want the avatar to lip-sync to it. Keep avatar in the audio request and omit voice.

2. Poll until it's done

curl --fail-with-body -sS --connect-timeout 10 --max-time 60 https://api.hiapi.ai/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Read data.status: queued, handling, and archiving are nonterminal; stop on success or fail. Poll every few seconds with a deadline. If a GET fails or the deadline expires, retain TASK_ID and continue querying that task later.

3. Download the output

On success, find the item with type: "video" in data.output and download its url. If captions were requested, also save the caption item. Each output item's expireAt is a Unix timestamp in seconds; download before that time. 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 generally reduce the billed output length; 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? The API supports color/image backgrounds and a separate remove_background option. Recipe 1's historical clip kept its office backdrop despite a color setting; use that as a reason to check your chosen preset and settings, not as a rule for every avatar.

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 optional, independent 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 for your intended delivery format; pricing stays $0.15 per rendered second. Check the actual downloaded dimensions before delivery.

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

Copy the business script and Generate with this prompt → Select the matching avatar, voice, 16:9, and 1080p; use the API tutorial for a complete integration example.