how-tos

Hướng dẫn HeyGen Avatar 6 API: video nói chuyện đầu tiên với cURL và Python

Poyo.ai Team
10 min read
Share:

Hướng dẫn HeyGen Avatar 6 API: video nói chuyện đầu tiên với cURL và Python

Hướng dẫn HeyGen Avatar 6 API này đưa bạn từ API key đến một video nói chuyện hoàn chỉnh trên PoYo. Bạn gửi một request JSON với model ID heygen-avatar-6 (hoặc heygen-avatar-6-turbo), giữ task ID được trả về, rồi polling cho đến khi MP4 sẵn sàng. Mọi request body bên dưới đều theo đúng dạng trong tài liệu PoYo; trang model HeyGen Avatar 6 có Playground nếu bạn muốn xem các đầu vào trước.

Trước khi bắt đầu

  • Tạo key tại poyo.ai/dashboard/api-key và export thành POYO_API_KEY. Giữ key trên server của bạn.
  • Lưu mọi file đầu vào tại URL HTTP hoặc HTTPS công khai, tải trực tiếp được. PoYo tự lấy media; không chấp nhận upload trong request.
  • Chọn tier. Cả hai ID nhận cùng các field. Turbo có giá 10 credit ($0.05) mỗi giây ở 1080p; Avatar 6 có giá 20 credit ($0.10). Xem Avatar 6 vs Turbo.

Request HeyGen Avatar 6 API đầu tiên với cURL

Request đầu tiên nhanh nhất hoàn toàn không cần media: một avatar công khai của HeyGen sẽ đọc văn bản của bạn.

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'

Một phản hồi thành công có "code": 200 và data.task_id, với status là not_started. Đó là một job trong hàng đợi, chưa phải video. Hãy polling:

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Các trạng thái là not_started, running, finished và failed. Khi finished, MP4 nằm trong data.files[] với file_type là video, và data.credits_amount cho biết số đã bị tính phí. Khi failed, hãy đọc data.error_message.

Vòng lặp polling Python có giới hạn

Trong các thử nghiệm ngày ra mắt 19 tháng 11 năm 2026, các clip văn bản ngắn mất khoảng 2 đến 2.4 phút từ lúc gửi đến khi có kết quả. Vòng lặp này polling mỗi 5 giây (tài liệu trạng thái khuyến nghị 2–5 giây), dừng ở 15 phút, và không bao giờ gửi lại khi hết thời gian chờ, vì lần gửi thứ hai là một task tính phí thứ hai.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(f"{body.get('code')} {err.get('type')}: {err.get('message')}")
    return body["data"]


def generate(payload, timeout_s=900):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    print("task", task_id, flush=True)
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        time.sleep(5)
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            videos = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "video"]
            return videos[0], task.get("credits_amount")
    raise TimeoutError("still running; poll this task again later: " + task_id)


url, credits = generate({
    "model": "heygen-avatar-6",
    "input": {
        "image_urls": ["https://example.com/presenter.png"],
        "audio_url": "https://example.com/speech.mp3",
        "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
        "resolution": "1080p",
    },
})
print(url, credits)

Với production, hãy thêm callback_url ở cấp cao nhất thay vì polling. PoYo POST cùng đối tượng task (không có lớp bọc code / data) khi task finished hoặc failed, được ký bằng HMAC-SHA256 trong X-Webhook-Signature; tài liệu webhook nêu quy tắc chữ ký.

Ba chế độ đầu vào của HeyGen Avatar 6 API

Không có công tắc chế độ. avatar chọn chế độ avatar công khai; nếu không có, video_url chọn chế độ video tham chiếu; nếu không có nữa, request chạy ở chế độ ảnh. Mỗi request chỉ dùng đầu vào của một chế độ.

Chế độ avatar công khai với văn bản

Như ví dụ ở trên. avatar là một trong 1,248 diện mạo công khai, text tối đa 1,000 ký tự, và voice là một trong 102 giọng (mặc định Warm Pro Narrator). Hướng dẫn văn bản thành avatar trình bày cách chọn diện mạo và giọng từ danh mục.

Chế độ avatar công khai với âm thanh của bạn

Thay text và voice bằng audio_url. aspect_ratio vẫn áp dụng:

{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Abigail Sofa Front",
    "audio_url": "https://example.com/speech.mp3",
    "aspect_ratio": "9:16"
  }
}

Chế độ ảnh

Một bức ảnh người thật cộng lời nói. Video giữ tỷ lệ khung hình của ảnh, nên hãy cắt ảnh theo khung bạn muốn trước khi gửi. callback_url nằm ngang hàng với model, không nằm trong input:

{
  "model": "heygen-avatar-6",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "image_urls": ["https://example.com/presenter.png"],
    "audio_url": "https://example.com/speech.mp3",
    "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
    "resolution": "1080p"
  }
}

Chế độ video tham chiếu

Dành cho nhân vật hoạt hình hoặc minh họa. video_url là một clip của nhân vật; image_urls tùy chọn thêm một ảnh tĩnh của cùng nhân vật. Đầu ra giữ tỷ lệ khung hình của clip:

{
  "model": "heygen-avatar-6-turbo",
  "input": {
    "video_url": "https://example.com/cartoon-character.mp4",
    "image_urls": ["https://example.com/cartoon-character.png"],
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "2K"
  }
}

Quy tắc kiểm tra field của HeyGen Avatar 6 API

Hãy kiểm tra những điều này trong code của bạn trước khi gửi; đây là các giới hạn được ghi trong tài liệu.

FieldChế độQuy tắc
modelTất cảheygen-avatar-6 hoặc heygen-avatar-6-turbo
image_urlsẢnh (bắt buộc), video tham chiếu (tùy chọn)Mảng gồm đúng một URL
video_urlVideo tham chiếuÍt nhất 2 giây, tối đa 50 MB
avatarAvatar công khaiMột trong 1,248 tên được liệt kê
audio_urlẢnh, video tham chiếu; hoặc avatar công khai thay cho text2–60 giây, tối đa 15 MB
textAvatar công khai1–1,000 ký tự
voiceAvatar công khai với textMột trong 102 tên
promptTất cảTối đa 1,200 ký tự
aspect_ratioAvatar công khai16:9, 9:16, 1:1, 4:5, 5:4
resolutionTất cả1080p (mặc định) hoặc 2K

Tên avatar và giọng được khớp bất kể chữ hoa/thường và khoảng trắng thừa, với một ngoại lệ được ghi trong tài liệu: Hope và Hope (có khoảng trắng ở cuối) là hai giọng khác nhau. Schema đầu vào không cho phép field thừa, nên đừng gửi các tùy chọn gốc của HeyGen như motion_expressiveness hay motion_prompt từ API riêng của HeyGen; trên PoYo, chỉ dẫn chuyển động được viết trong prompt.

Các lỗi cần xử lý

Luôn đọc code trong body phản hồi. Một số lỗi kiểm tra trả về HTTP 200 với "code": 400, nên chỉ kiểm tra mã trạng thái HTTP là chưa đủ.

code trong bodyerror.typeCách xử lý
400validation_error và các loại khácSửa đầu vào: âm thanh ngoài khoảng 2–60 giây, tên avatar không tồn tại, field của chế độ khác. Đừng thử lại nguyên trạng
401authentication_errorKiểm tra header Authorization: Bearer
402insufficient_credits_errorNạp thêm, hoặc chờ các task văn bản đang chạy được quyết toán (xem bên dưới)
429rate_limit_errorGiãn thời gian rồi thử lại
500 / 502 / 503internal_error, upstream_error, service_errorThử lại với exponential backoff

Độ dài âm thanh, độ dài video tham chiếu và tên avatar được kiểm tra khi gửi, nên những lỗi này xuất hiện ngay dưới dạng 400 thay vì một task thất bại vài phút sau.

Trường hợp 402 có một điểm đặc thù với HeyGen. Trong thử nghiệm ngày ra mắt, sau khi đã gửi hai task văn bản, request thứ ba (Turbo, 2K, 22 từ) trả về HTTP 200 với code 402 trong body và loại insufficient_credits_error: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Task văn bản giữ credit trong khi chạy, nên gửi dồn dập nhiều task văn bản có thể gặp 402 ngay cả khi tổng phí cuối cùng vẫn nằm trong số dư. Hãy xếp hàng các job văn bản, hoặc hiển thị thông báo lỗi cho người dùng, vì nó đã nêu sẵn cả hai con số.

Cách tính hóa đơn HeyGen Avatar 6 API đầu tiên

PoYo tính phí theo giây đầu ra, làm tròn lên thành giây nguyên (1 credit = $0.005):

Model1080p2K
heygen-avatar-6-turbo10 credit ($0.05) / giây18 credit ($0.09) / giây
heygen-avatar-620 credit ($0.10) / giây29 credit ($0.145) / giây
  • Với audio_url (mọi chế độ): phí bằng độ dài âm thanh, làm tròn lên, bị trừ khi gửi. Một clip 12.3 giây trên Avatar 6 ở 1080p là 13 × 20 = 260 credit ($1.30).
  • Với text: credit được giữ trước khi gửi và quyết toán theo độ dài video hoàn chỉnh khi task kết thúc. Trong thử nghiệm của chúng tôi, một kịch bản 27 từ trên Turbo cho ra 10.16 giây và được tính là 11 giây, tức 110 credit (11 giây × 10, $0.55) theo giá hiện tại; một kịch bản 21 từ trên Avatar 6 cho ra 6.88 giây và được tính là 7 giây, tức 140 credit (7 giây × 20, $0.70) theo giá hiện tại.

data.credits_amount trên task đã hoàn tất là con số dùng để đối chiếu. Thêm ví dụ có trong giá HeyGen Avatar 6 API.

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

Làm sao gọi HeyGen Avatar 6 API từ Python?

POST JSON đến https://api.poyo.ai/api/generate/submit bằng requests, rồi polling /api/generate/status/{task_id} với một hạn chót, như vòng lặp ở trên. Bất kỳ HTTP client nào cũng dùng được; không bắt buộc SDK.

HeyGen Avatar 6 API có callback không?

Có. Thêm callback_url ở cấp cao nhất của request. PoYo POST dữ liệu task khi task hoàn tất hoặc thất bại.

Vì sao request HeyGen Avatar 6 API của tôi trả về HTTP 200 nhưng không có task?

Hãy đọc body. code khác 200 nghĩa là request đã thất bại, dù HTTP là 200; error.message cho biết lý do.

Tôi có thể upload file trực tiếp lên HeyGen Avatar 6 API không?

Không. image_urls, video_url và audio_url nhận URL HTTP hoặc HTTPS công khai để PoYo tải về.

Kết quả HeyGen Avatar 6 API được lưu bao lâu?

Video được tạo có thể truy cập trong 3 ngày sau khi tạo. Hãy tải MP4 về kho lưu trữ của bạn.

Share: