![]()
Bu HeyGen Avatar 6 API rehberi, sizi bir API anahtarından PoYo'da bitmiş bir konuşan videoya götürür. heygen-avatar-6 (veya heygen-avatar-6-turbo) model kimliğiyle tek bir JSON isteği gönderir, dönen görev kimliğini saklar ve MP4 hazır olana kadar durumu sorgularsınız. Aşağıdaki tüm istek gövdeleri PoYo belgelerindeki biçimi izler; girdileri önce görmek isterseniz HeyGen Avatar 6 model sayfasında bir Playground bulunur.
Başlamadan önce
poyo.ai/dashboard/api-keyadresinde bir anahtar oluşturun vePOYO_API_KEYolarak dışa aktarın. Anahtarı sunucunuzda tutun.- Her girdi dosyasını herkese açık, doğrudan indirilebilir bir HTTP veya HTTPS URL'sinde barındırın. PoYo medyayı kendisi indirir; istek içinde dosya yüklemeyi kabul etmez.
- Bir katman seçin. İki kimlik de aynı alanları alır. Turbo 1080p'de saniye başına 10 kredi ($0.05); Avatar 6 ise 20 kredi ($0.10) tutar. Bkz. Avatar 6 vs Turbo.
cURL ile ilk HeyGen Avatar 6 API isteğiniz
En hızlı ilk istek hiç medya gerektirmez: herkese açık bir HeyGen avatarı metninizi okur.
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"
}
}'
Başarılı bir yanıtta "code": 200 ve data.task_id bulunur, status ise not_started olur. Bu bir video değil, kuyruktaki bir iştir. Durumunu sorgulayın:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Durumlar not_started, running, finished ve failed şeklindedir. finished olduğunda MP4, file_type değeri video olan data.files[] içinde yer alır ve data.credits_amount alınan ücreti gösterir. failed olduğunda data.error_message alanını okuyun.
Sınırlı bir Python sorgulama döngüsü
19 Kasım 2026'daki lansman günü testlerimizde kısa metin klipleri, gönderimden sonuca kadar yaklaşık 2 ile 2.4 dakika sürdü. Bu döngü 5 saniyede bir sorgular (durum belgeleri 2–5 s önerir), 15 dakikada durur ve zaman aşımında asla yeniden göndermez; çünkü ikinci bir gönderim, ücretlendirilen ikinci bir görevdir.
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)
Üretim ortamında sorgulama yerine en üst düzeye bir callback_url ekleyin. PoYo, görev finished veya failed olduğunda aynı görev nesnesini (code / data sarmalayıcısı olmadan) X-Webhook-Signature içinde HMAC-SHA256 ile imzalayarak gönderir; imza kuralı webhook belgelerinde yer alıyor.
HeyGen Avatar 6 API'nin üç girdi modu
Mod anahtarı yoktur. avatar herkese açık avatar modunu seçer; o yoksa video_url referans video modunu seçer; o da yoksa istek fotoğraf modunda çalışır. Her istekte tek bir modun girdilerini kullanın.
Metinle herkese açık avatar modu
Yukarıda gösterildi. avatar 1,248 herkese açık görünümden biridir, text en fazla 1,000 karakterdir ve voice 102 sesten biridir (varsayılan Warm Pro Narrator). Text-to-avatar rehberi, katalogdan görünüm ve ses seçmeyi anlatıyor.
Kendi sesinizle herkese açık avatar modu
text ve voice yerine audio_url kullanın. aspect_ratio yine geçerlidir:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Fotoğraf modu
Gerçek bir kişinin tek fotoğrafı artı konuşma. Video fotoğrafın en-boy oranını korur; bu yüzden göndermeden önce fotoğrafı istediğiniz kadraja kırpın. callback_url, input içinde değil, model ile aynı düzeyde yer alır:
{
"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"
}
}
Referans video modu
Animasyonlu veya çizim karakterler için. video_url karakterin bir klibidir; image_urls isteğe bağlı olarak aynı karakterin tek bir durağan görüntüsünü ekler. Çıktı klibin en-boy oranını korur:
{
"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"
}
}
HeyGen Avatar 6 API alan doğrulama kuralları
Göndermeden önce bunları kendi kodunuzda kontrol edin; bunlar belgelenmiş limitlerdir.
| Alan | Mod | Kural |
|---|---|---|
model | Tümü | heygen-avatar-6 veya heygen-avatar-6-turbo |
image_urls | Fotoğraf (zorunlu), referans video (isteğe bağlı) | Tam olarak bir URL içeren dizi |
video_url | Referans video | En az 2 s, en fazla 50 MB |
avatar | Herkese açık avatar | Listelenen 1,248 addan biri |
audio_url | Fotoğraf, referans video; veya text yerine herkese açık avatar | 2–60 s, en fazla 15 MB |
text | Herkese açık avatar | 1–1,000 karakter |
voice | text ile herkese açık avatar | 102 addan biri |
prompt | Tümü | En fazla 1,200 karakter |
aspect_ratio | Herkese açık avatar | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Tümü | 1080p (varsayılan) veya 2K |
Avatar ve ses adları büyük/küçük harf ve fazladan boşluklardan bağımsız eşleşir; belgelenmiş tek bir istisna vardır: Hope ve Hope (sonunda boşluk olan) iki farklı sestir. Girdi şeması ek alanlara izin vermez; bu yüzden HeyGen'in kendi API'sindeki motion_expressiveness veya motion_prompt gibi HeyGen'e özgü seçenekleri göndermeyin; PoYo'da hareket yönlendirmesi prompt alanına yazılır.
Ele alınmaya değer hatalar
Yanıt gövdesindeki code değerini her zaman okuyun. Bazı doğrulama hataları HTTP 200 ile "code": 400 olarak döner; bu yüzden yalnızca HTTP durumunu kontrol etmek yeterli değildir.
Gövdedeki code | error.type | Ne yapmalı |
|---|---|---|
| 400 | validation_error ve diğerleri | Girdiyi düzeltin: 2–60 s dışında ses, bilinmeyen avatar adı, başka bir moddan alan. Değiştirmeden yeniden denemeyin |
| 401 | authentication_error | Authorization: Bearer başlığını kontrol edin |
| 402 | insufficient_credits_error | Bakiye yükleyin veya çalışan metin görevlerinin hesaplaşmasını bekleyin (aşağıda) |
| 429 | rate_limit_error | Bekleyip yeniden deneyin |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Üstel geri çekilmeyle yeniden deneyin |
Ses süresi, referans video süresi ve avatar adı gönderim sırasında kontrol edilir; bu yüzden bu hatalar dakikalar sonra başarısız bir görev olarak değil, anında 400 olarak ortaya çıkar.
402 durumunun HeyGen'e özgü bir ayrıntısı var. Lansman günü testimizde iki metin görevi gönderildikten sonra üçüncü bir istek (Turbo, 2K, 22 kelime), gövdesinde code 402 ve insufficient_credits_error türüyle HTTP 200 olarak döndü: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Metin görevleri çalıştıkları sürece kredi tutar; bu yüzden art arda gönderilen metin istekleri, nihai ücretler sığacak olsa bile 402 alabilir. Metin işlerini kuyruğa alın veya hata mesajını kullanıcıya gösterin; mesaj iki sayıyı da zaten belirtiyor.
İlk HeyGen Avatar 6 API faturası nasıl hesaplanır
PoYo, tam saniyeye yukarı yuvarlanmış çıktı saniyesi başına ücretlendirir (1 kredi = $0.005):
| Model | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 kredi ($0.05) / s | 18 kredi ($0.09) / s |
heygen-avatar-6 | 20 kredi ($0.10) / s | 29 kredi ($0.145) / s |
audio_urlile (tüm modlar): ücret, yukarı yuvarlanmış ses süresidir ve gönderim sırasında alınır. Avatar 6'da 1080p'de 12.3 saniyelik bir klip 13 × 20 = 260 kredi ($1.30) eder.textile: krediler gönderim sırasında ayrılır ve görev bittiğinde bitmiş videonun süresine göre hesaplaşılır. Testlerimizde Turbo'da 27 kelimelik bir metin 10.16 s üretti ve 11 saniye olarak ücretlendirildi, bu da güncel fiyatlarla 110 kredi (11 s × 10, $0.55) eder; Avatar 6'da 21 kelimelik bir metin 6.88 s üretti ve 7 saniye olarak ücretlendirildi, bu da güncel fiyatlarla 140 kredi (7 s × 20, $0.70) eder.
Biten görevdeki data.credits_amount, mutabakat için esas alınacak sayıdır. Daha fazla örnek HeyGen Avatar 6 API fiyatlandırması yazısında.
Sıkça sorulan sorular
HeyGen Avatar 6 API'yi Python'dan nasıl çağırırım?
requests ile https://api.poyo.ai/api/generate/submit adresine JSON POST edin, ardından yukarıdaki döngüde olduğu gibi bir süre sınırıyla /api/generate/status/{task_id} sorgulayın. Herhangi bir HTTP istemcisi çalışır; SDK gerekmez.
HeyGen Avatar 6 API'nin callback'i var mı?
Evet. İsteğin en üst düzeyine callback_url ekleyin. PoYo, görev bittiğinde veya başarısız olduğunda görev verilerini gönderir.
HeyGen Avatar 6 API isteğim neden HTTP 200 döndü ama görev oluşmadı?
Gövdeyi okuyun. 200'den farklı bir code, HTTP 200 olsa bile isteğin başarısız olduğu anlamına gelir; nedeni error.message söyler.
HeyGen Avatar 6 API'ye doğrudan dosya yükleyebilir miyim?
Hayır. image_urls, video_url ve audio_url, PoYo'nun indirdiği herkese açık HTTP veya HTTPS URL'leri alır.
HeyGen Avatar 6 API sonuçları ne kadar süre saklanır?
Üretilen videolar oluşturulduktan sonra 3 gün erişilebilir. MP4'ü kendi depolama alanınıza indirin.