how-tos

HeyGen Avatar 6 API văn bản thành avatar: video người dẫn từ kịch bản, không cần file âm thanh

Poyo.ai Team
10 min read
Share:

HeyGen Avatar 6 API văn bản thành avatar: video người dẫn từ kịch bản

HeyGen Avatar 6 API có thể tạo video người dẫn chỉ từ một kịch bản. Ở chế độ avatar công khai, bạn chỉ định một trong 1,248 diện mạo có sẵn của HeyGen, gửi tối đa 1,000 ký tự text, chọn một trong 102 giọng, và heygen-avatar-6 (hoặc heygen-avatar-6-turbo) trả về một MP4 khớp khẩu hình. Không cần ảnh, không cần bản thu âm, không cần bước chuyển văn bản thành giọng nói ở phía bạn. Hướng dẫn này trình bày cách chọn diện mạo và giọng từ danh mục, chỉ đạo cử chỉ bằng prompt, chọn khung hình và chi phí của một request văn bản. Bạn cũng có thể duyệt các diện mạo trên trang model HeyGen Avatar 6.

Request văn bản thành avatar

Đây là body được ghi trong tài liệu cho chế độ avatar công khai với văn bản:

{
  "model": "heygen-avatar-6-turbo",
  "input": {
    "avatar": "Abigail Office Front",
    "text": "Hello and welcome to this demonstration of HeyGen Avatar 6.",
    "voice": "Warm Pro Narrator",
    "prompt": "Speak with calm confidence and nod slightly at the end.",
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }
}
FieldBắt buộcQuy tắc
avatarCóMột trong 1,248 tên diện mạo
textCó (thay cho audio_url)1–1,000 ký tự
voiceKhôngMột trong 102 tên; mặc định Warm Pro Narrator
promptKhôngTối đa 1,200 ký tự chỉ đạo
aspect_ratioKhông16:9 (mặc định), 9:16, 1:1, 4:5, 5:4
resolutionKhông1080p (mặc định) hoặc 2K

Sự có mặt của avatar là yếu tố chọn chế độ này. Đừng gửi kèm image_urls hay video_url; mỗi request chỉ dùng đầu vào của một chế độ. Gửi đến POST https://api.poyo.ai/api/generate/submit và polling /api/generate/status/{task_id} như trong hướng dẫn HeyGen Avatar 6 API.

Chọn diện mạo avatar từ danh mục

PoYo công bố mọi tên trên trang Avatars and Voices và dưới dạng danh mục JSON. Danh mục có năm key:

KeyNội dung
modelsheygen-avatar-6, heygen-avatar-6-turbo (cùng các tên dùng được trên cả hai)
default_voiceWarm Pro Narrator
avatarsToàn bộ 1,248 tên diện mạo, danh sách phẳng
avatars_by_personCùng các diện mạo đó, nhóm theo 156 người
voicesToàn bộ 102 tên giọng

Mỗi người có một hoặc nhiều diện mạo, và mỗi diện mạo là một giá trị avatar riêng. Abigail có năm (Abigail (Upper Body), Abigail Office Front, Abigail Office Side, Abigail Sofa Front, Abigail Sofa Side); Annie có 54; tám người chỉ có một diện mạo. Tên mô tả bối cảnh, trang phục và góc máy, thường đủ để chọn mà không cần xem trước:

Bạn muốnTìm tên cóVí dụ
Người dẫn nhìn thẳng máy quayFrontAbigail Office Front, Bryan Suit Front
Góc ba phần tưSideAbigail Office Side
Ngồi, thoải máiSofa, Sitting, LoungeAnnie Sofa Sitting Front
Một vai trò hoặc bối cảnhDoctor, Nurse, Yoga, Tech ExpertAnn Doctor Standing, Adriana Nurse Front, Amelia Yoga Front, Bryan Tech Expert

Khoảng 480 tên chứa Front và khoảng 430 tên chứa Side. Với một loạt video giải thích, hãy chọn một người và dùng các diện mạo Front của họ, để người dẫn giữ nguyên qua các video. Dùng diện mạo Side tương ứng cho các cảnh chèn.

Tên được khớp bất kể chữ hoa/thường và khoảng trắng thừa, nên abigail office front sẽ chọn Abigail Office Front. PoYo đối chiếu avatar với danh sách khi gửi, nên lỗi chính tả trả về 400 ngay lập tức thay vì một task thất bại. Hãy kiểm tra trong code của bạn trước:

import requests

catalog = requests.get(
    "https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()

def norm(name: str) -> str:
    return " ".join(name.split()).lower()

AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])

def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
    if norm(avatar) not in AVATARS:
        raise ValueError(f"unknown avatar: {avatar!r}")
    if not 1 <= len(text) <= 1000:
        raise ValueError("text must be 1-1,000 characters")
    if voice is not None and voice not in VOICES:
        raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
    if prompt is not None and len(prompt) > 1200:
        raise ValueError("prompt must be at most 1,200 characters")
    body = {"avatar": AVATARS[norm(avatar)], "text": text,
            "aspect_ratio": aspect_ratio, "resolution": resolution}
    if voice:
        body["voice"] = voice
    if prompt:
        body["prompt"] = prompt
    return {"model": model, "input": body}

Phần kiểm tra giọng cố ý dùng tên chính xác; phần tiếp theo giải thích lý do.

Chọn giọng

voice quyết định ai đọc text. Bỏ qua thì bạn sẽ có Warm Pro Narrator. 102 giọng gồm tên thông thường (Andrew, Ivy, Jessica Anne Bogart), tên mô tả (Calm Chloe, Professor Dean, Radio Rick, Chill Brian) và một số có thẻ phong cách trong tên.

Ba điều hay gây vấp:

  • Khoảng trắng ở cuối có thể quan trọng. Tài liệu chỉ rõ Hope và Hope (có khoảng trắng ở cuối) là hai giọng khác nhau. Archer , Cassidy , Adam Stone , Spuds Oxley và Andrew Rizz cũng kết thúc bằng khoảng trắng trong danh mục. Hãy sao chép tên từ JSON thay vì gõ lại.
  • Một số tên chứa emoji hoặc hậu tố giống tên file, như Cute Chloe - Friendly 😊 hoặc Brenda - UGC - 1.mp4. Các ký tự đó là một phần của tên. Gửi request body dưới dạng JSON UTF-8 và tên sẽ được truyền nguyên vẹn.
  • Giọng không gắn với avatar. Bất kỳ giọng nào trong 102 giọng cũng có thể đọc cho bất kỳ diện mạo nào trong 1,248 diện mạo. Hãy chọn giọng hợp với người trên màn hình; các thử nghiệm ngày ra mắt của chúng tôi ghép Bryan Tech Expert với Andrew và Abigail Office Front với Jessica Anne Bogart.

voice chỉ áp dụng khi bạn gửi text. Nếu bạn gửi audio_url thay thế, avatar sẽ nói theo bản thu của bạn và voice không được dùng.

Chỉ đạo cử chỉ bằng prompt

prompt nhận tối đa 1,200 ký tự chỉ đạo về cử chỉ, biểu cảm và tư thế. Báo cáo kỹ thuật của HeyGen mô tả kỹ thuật này: "Hãy viết hành động ngay cạnh lời thoại. Avatar 6 sẽ thực hiện đúng thời điểm." Ví dụ của họ: "Dược sĩ thân thiện. Ở 'Hello', giơ ngón cái. Ở 'the counter on the left', chỉ sang bên bằng ngón trỏ."

Một mẫu theo định dạng đó:

{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Bryan Tech Expert",
    "text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
    "voice": "Andrew",
    "prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }
}

Mẹo để prompt hữu ích:

  • Trích dẫn chính xác những từ trong text mà mỗi hành động cần rơi vào, để tín hiệu rõ ràng.
  • Mô tả một vai trò hoặc tâm trạng trước ("Friendly product expert"), rồi đến các tín hiệu.
  • Bỏ prompt khi bạn không có tín hiệu cụ thể. Trang ra mắt Avatar 6 của HeyGen cho biết model tự "khớp cử chỉ, cảm xúc và biểu cảm với kịch bản của bạn".

Chọn tỷ lệ khung hình theo vị trí đăng

aspect_ratio chỉ có ở chế độ avatar công khai; chế độ ảnh và video tham chiếu giữ hình dạng của đầu vào.

Vị trí đăngaspect_ratio
Website, YouTube, bài học LMS16:9 (mặc định)
Shorts, Reels, TikTok, stories9:16
Bài đăng feed vuông, thẻ trong ứng dụng1:1
Bài đăng feed dọc4:5
Bài đăng feed ngang5:4

resolution là thiết lập riêng: 1080p hoặc 2K ở bất kỳ tỷ lệ nào. 2K đắt hơn mỗi giây, nên hãy render bản nháp ở 1080p.

Video dài bao lâu và chi phí bao nhiêu

Với văn bản, video dài bằng thời gian avatar đọc hết, tối đa 1,000 ký tự. Bạn bị tính phí theo độ dài video hoàn chỉnh, làm tròn lên thành giây nguyên. Credit được giữ trước khi bạn gửi và quyết toán theo số giây thực tế khi task hoàn tất.

Các thử nghiệm ngày ra mắt của chúng tôi trên API production, 19 tháng 11 năm 2026 (16:9, 1080p):

ModelAvatar / giọngKịch bảnĐầu raChi phí theo giá hiện tạiThời gian thực tế
heygen-avatar-6-turboAbigail Office Front / Jessica Anne Bogart27 từ10.16 giây110 credit ($0.55)Khoảng 2.4 phút
heygen-avatar-6Bryan Tech Expert / Andrew21 từ6.88 giây140 credit ($0.70)Khoảng 2 phút

Tính ra khoảng 2.7 và 3.1 từ mỗi giây trong hai lần chạy này, hữu ích để ước tính ngân sách sơ bộ nhưng không phải cam kết, vì nhịp đọc thay đổi theo giọng và kịch bản. Giá mỗi giây: Turbo 10 credit ($0.05) ở 1080p hoặc 18 ($0.09) ở 2K; Avatar 6 20 credit ($0.10) hoặc 29 ($0.145). Xem giá HeyGen Avatar 6 API để biết thêm.

Vì task văn bản giữ phần giữ trước trong khi chạy, gửi nhiều task cùng lúc có thể trả về HTTP 200 với code 402 trong body (insufficient_credits_error). Trong thử nghiệm của chúng tôi, request thứ ba bị từ chối với: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Hãy xếp hàng các job văn bản, hoặc duy trì số dư đủ cho phần giữ trước đang chạy. Dùng Turbo trong lúc lặp lại; so sánh Avatar 6 vs Turbo cho biết khi nào nên chuyển.

Câu hỏi thường gặp

HeyGen Avatar 6 API có biến văn bản thành video avatar nói chuyện được không?

Được. Ở chế độ avatar công khai, gửi avatar, tối đa 1,000 ký tự text, và voice tùy chọn. Không cần file âm thanh.

Danh sách avatar và giọng của HeyGen Avatar 6 API ở đâu?

Trên trang tài liệu PoYo Avatars and Voices, và dưới dạng danh mục JSON có thể tải về với các key avatars, avatars_by_person và voices.

Giọng mặc định của HeyGen Avatar 6 API là gì?

Warm Pro Narrator, được dùng khi bỏ qua voice.

Tôi có thể dùng ảnh của mình với văn bản thay vì avatar có sẵn không?

Không. text chỉ hoạt động ở chế độ avatar công khai. Với ảnh của bạn, hãy dùng chế độ ảnh với image_urls và audio_url; tạo âm thanh bằng một model TTS trước nếu cần.

Văn bản thành avatar của HeyGen Avatar 6 hỗ trợ những tỷ lệ khung hình nào?

16:9, 9:16, 1:1, 4:5 và 5:4, ở 1080p hoặc 2K.

Request văn bản của HeyGen Avatar 6 API được tính phí thế nào?

Theo độ dài video hoàn chỉnh, làm tròn lên thành giây nguyên, nhân với giá mỗi giây của model. Credit được giữ trước khi gửi và quyết toán khi task kết thúc.

Share: