![]()
Panduan HeyGen Avatar 6 API ini membawa Anda dari API key hingga video berbicara yang jadi di PoYo. Anda mengirim satu request JSON dengan ID model heygen-avatar-6 (atau heygen-avatar-6-turbo), menyimpan task ID yang dikembalikan, lalu melakukan polling hingga MP4 siap. Setiap body request di bawah mengikuti bentuk dari dokumentasi PoYo; halaman model HeyGen Avatar 6 memiliki Playground jika Anda ingin melihat input-nya terlebih dahulu.
Sebelum memulai
- Buat key di
poyo.ai/dashboard/api-keydan export sebagaiPOYO_API_KEY. Simpan di server Anda. - Host setiap file input di URL HTTP atau HTTPS yang publik dan dapat diunduh langsung. PoYo mengambil media itu sendiri; PoYo tidak menerima upload di dalam request.
- Pilih tier. Kedua ID menerima field yang sama. Turbo berbiaya 10 kredit ($0.05) per detik di 1080p; Avatar 6 berbiaya 20 kredit ($0.10). Lihat Avatar 6 vs Turbo.
Request HeyGen Avatar 6 API pertama Anda dengan cURL
Request pertama yang paling cepat tidak membutuhkan media sama sekali: avatar publik HeyGen membacakan teks Anda.
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"
}
}'
Respons yang berhasil berisi "code": 200 dan data.task_id, dengan status bernilai not_started. Itu adalah job dalam antrean, bukan video. Lakukan polling:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Status-nya adalah not_started, running, finished, dan failed. Saat finished, MP4 ada di data.files[] dengan file_type video, dan data.credits_amount menunjukkan biaya yang ditagih. Saat failed, baca data.error_message.
Loop polling Python berbatas
Dalam uji hari peluncuran kami pada 19 November 2026, klip teks pendek membutuhkan sekitar 2 hingga 2.4 menit dari submit hingga hasil. Loop ini melakukan polling setiap 5 detik (dokumentasi status merekomendasikan 2–5 dtk), berhenti di 15 menit, dan tidak pernah submit ulang saat timeout, karena submit kedua berarti task kedua yang ditagih.
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)
Untuk produksi, tambahkan callback_url di level teratas alih-alih polling. PoYo mengirim objek task yang sama (tanpa pembungkus code / data) saat task finished atau failed, ditandatangani dengan HMAC-SHA256 di X-Webhook-Signature; dokumentasi webhook menjelaskan aturan tanda tangannya.
Tiga mode input HeyGen Avatar 6 API
Tidak ada sakelar mode. avatar memilih mode avatar publik; jika tidak ada, video_url memilih mode video referensi; jika tidak ada juga, request berjalan dalam mode foto. Gunakan input dari satu mode per request.
Mode avatar publik dengan teks
Seperti contoh di atas. avatar adalah salah satu dari 1,248 tampilan publik, text hingga 1,000 karakter, dan voice adalah salah satu dari 102 suara (default Warm Pro Narrator). Panduan teks ke avatar membahas cara memilih tampilan dan suara dari katalog.
Mode avatar publik dengan audio Anda
Ganti text dan voice dengan audio_url. aspect_ratio tetap berlaku:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Mode foto
Satu foto orang sungguhan plus ucapan. Video mempertahankan rasio aspek foto, jadi crop foto ke frame yang Anda inginkan sebelum mengirimnya. callback_url berada sejajar dengan model, bukan di dalam 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"
}
}
Mode video referensi
Untuk karakter animasi atau ilustrasi. video_url adalah klip karakter tersebut; image_urls dapat menambahkan satu gambar diam dari karakter yang sama secara opsional. Output mempertahankan rasio aspek klip:
{
"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"
}
}
Aturan validasi field HeyGen Avatar 6 API
Periksa ini di kode Anda sendiri sebelum submit; ini adalah batas yang terdokumentasi.
| Field | Mode | Aturan |
|---|---|---|
model | Semua | heygen-avatar-6 atau heygen-avatar-6-turbo |
image_urls | Foto (wajib), video referensi (opsional) | Array berisi tepat satu URL |
video_url | Video referensi | Minimal 2 dtk, maksimal 50 MB |
avatar | Avatar publik | Salah satu dari 1,248 nama yang terdaftar |
audio_url | Foto, video referensi; atau avatar publik sebagai pengganti text | 2–60 dtk, maksimal 15 MB |
text | Avatar publik | 1–1,000 karakter |
voice | Avatar publik dengan text | Salah satu dari 102 nama |
prompt | Semua | Hingga 1,200 karakter |
aspect_ratio | Avatar publik | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Semua | 1080p (default) atau 2K |
Nama avatar dan suara dicocokkan tanpa memedulikan huruf besar-kecil dan spasi berlebih, dengan satu pengecualian yang terdokumentasi: Hope dan Hope (spasi di akhir) adalah dua suara yang berbeda. Skema input tidak mengizinkan field tambahan, jadi jangan kirim opsi bawaan HeyGen seperti motion_expressiveness atau motion_prompt dari API HeyGen sendiri; di PoYo, arahan gerakan ditulis di prompt.
Error yang perlu ditangani
Selalu baca code di body respons. Beberapa error validasi kembali sebagai HTTP 200 dengan "code": 400, jadi memeriksa status HTTP saja tidak cukup.
code di body | error.type | Yang harus dilakukan |
|---|---|---|
| 400 | validation_error dan lainnya | Perbaiki input: audio di luar 2–60 dtk, nama avatar tidak dikenal, field dari mode lain. Jangan retry tanpa perubahan |
| 401 | authentication_error | Periksa header Authorization: Bearer |
| 402 | insufficient_credits_error | Isi ulang saldo, atau tunggu task teks yang sedang berjalan selesai diproses (lihat di bawah) |
| 429 | rate_limit_error | Tunda lalu coba lagi |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Retry dengan exponential backoff |
Durasi audio, durasi video referensi, dan nama avatar diperiksa saat submit, sehingga kesalahan ini muncul sebagai 400 seketika, bukan task gagal beberapa menit kemudian.
Kasus 402 punya kekhasan tersendiri pada HeyGen. Dalam uji hari peluncuran kami, setelah dua task teks di-submit, request ketiga (Turbo, 2K, 22 kata) kembali sebagai HTTP 200 dengan code 402 di body dan tipe 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 teks menahan kredit selama berjalan, sehingga rentetan submit teks bisa terkena 402 meski total biaya akhirnya masih muat di saldo. Masukkan job teks ke antrean, atau tampilkan pesan error kepada pengguna, karena pesan itu sudah menyebutkan kedua angkanya.
Cara menghitung tagihan HeyGen Avatar 6 API pertama
PoYo menagih per detik output, dibulatkan ke atas ke detik penuh (1 kredit = $0.005):
| Model | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 kredit ($0.05) / dtk | 18 kredit ($0.09) / dtk |
heygen-avatar-6 | 20 kredit ($0.10) / dtk | 29 kredit ($0.145) / dtk |
- Dengan
audio_url(semua mode): biaya sesuai durasi audio, dibulatkan ke atas, dipotong saat submit. Klip 12.3 detik di Avatar 6 1080p adalah 13 × 20 = 260 kredit ($1.30). - Dengan
text: kredit dicadangkan saat submit dan diselesaikan sesuai durasi video jadi saat task berakhir. Dalam uji kami, skrip 27 kata di Turbo menghasilkan 10.16 dtk dan ditagih sebagai 11 detik, yaitu 110 kredit (11 dtk × 10, $0.55) dengan harga saat ini; skrip 21 kata di Avatar 6 menghasilkan 6.88 dtk dan ditagih sebagai 7 detik, yaitu 140 kredit (7 dtk × 20, $0.70) dengan harga saat ini.
data.credits_amount pada task yang selesai adalah angka yang perlu dicocokkan. Contoh lainnya ada di harga HeyGen Avatar 6 API.
Pertanyaan yang sering diajukan
Bagaimana cara memanggil HeyGen Avatar 6 API dari Python?
POST JSON ke https://api.poyo.ai/api/generate/submit dengan requests, lalu lakukan polling ke /api/generate/status/{task_id} dengan batas waktu, seperti pada loop di atas. Klien HTTP apa pun bisa dipakai; SDK tidak wajib.
Apakah ada callback di HeyGen Avatar 6 API?
Ya. Tambahkan callback_url di level teratas request. PoYo mengirim data task saat task selesai atau gagal.
Mengapa request HeyGen Avatar 6 API saya mengembalikan HTTP 200 tetapi tidak ada task?
Baca body-nya. code selain 200 berarti request gagal, meski HTTP-nya 200; error.message menjelaskan alasannya.
Bisakah saya meng-upload file langsung ke HeyGen Avatar 6 API?
Tidak. image_urls, video_url, dan audio_url menerima URL HTTP atau HTTPS publik yang diunduh oleh PoYo.
Berapa lama hasil HeyGen Avatar 6 API disimpan?
Video yang dihasilkan dapat diakses selama 3 hari setelah dibuat. Unduh MP4 ke penyimpanan Anda sendiri.