![]()
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"
}
}
| Field | Bắt buộc | Quy tắc |
|---|---|---|
avatar | Có | Một trong 1,248 tên diện mạo |
text | Có (thay cho audio_url) | 1–1,000 ký tự |
voice | Không | Một trong 102 tên; mặc định Warm Pro Narrator |
prompt | Không | Tối đa 1,200 ký tự chỉ đạo |
aspect_ratio | Không | 16:9 (mặc định), 9:16, 1:1, 4:5, 5:4 |
resolution | Không | 1080p (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:
| Key | Nội dung |
|---|---|
models | heygen-avatar-6, heygen-avatar-6-turbo (cùng các tên dùng được trên cả hai) |
default_voice | Warm Pro Narrator |
avatars | Toàn bộ 1,248 tên diện mạo, danh sách phẳng |
avatars_by_person | Cùng các diện mạo đó, nhóm theo 156 người |
voices | Toà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ốn | Tìm tên có | Ví dụ |
|---|---|---|
| Người dẫn nhìn thẳng máy quay | Front | Abigail Office Front, Bryan Suit Front |
| Góc ba phần tư | Side | Abigail Office Side |
| Ngồi, thoải mái | Sofa, Sitting, Lounge | Annie Sofa Sitting Front |
| Một vai trò hoặc bối cảnh | Doctor, Nurse, Yoga, Tech Expert | Ann 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õ
HopevàHope(có khoảng trắng ở cuối) là hai giọng khác nhau.Archer,Cassidy,Adam Stone,Spuds OxleyvàAndrew Rizzcũ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ặcBrenda - 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 ExpertvớiAndrewvàAbigail Office FrontvớiJessica 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
textmà 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ỏ
promptkhi 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í đăng | aspect_ratio |
|---|---|
| Website, YouTube, bài học LMS | 16:9 (mặc định) |
| Shorts, Reels, TikTok, stories | 9:16 |
| Bài đăng feed vuông, thẻ trong ứng dụng | 1:1 |
| Bài đăng feed dọc | 4:5 |
| Bài đăng feed ngang | 5: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):
| Model | Avatar / giọng | Kịch bản | Đầu ra | Chi phí theo giá hiện tại | Thời gian thực tế |
|---|---|---|---|---|---|
heygen-avatar-6-turbo | Abigail Office Front / Jessica Anne Bogart | 27 từ | 10.16 giây | 110 credit ($0.55) | Khoảng 2.4 phút |
heygen-avatar-6 | Bryan Tech Expert / Andrew | 21 từ | 6.88 giây | 140 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.