how-tos

HeyGen Avatar 6 API Rehberi: cURL ve Python ile İlk Konuşan Video

Poyo.ai Team
8 min read
Share:

HeyGen Avatar 6 API rehberi: cURL ve Python ile ilk konuşan video

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-key adresinde bir anahtar oluşturun ve POYO_API_KEY olarak 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.

AlanModKural
modelTümüheygen-avatar-6 veya heygen-avatar-6-turbo
image_urlsFotoğraf (zorunlu), referans video (isteğe bağlı)Tam olarak bir URL içeren dizi
video_urlReferans videoEn az 2 s, en fazla 50 MB
avatarHerkese açık avatarListelenen 1,248 addan biri
audio_urlFotoğraf, referans video; veya text yerine herkese açık avatar2–60 s, en fazla 15 MB
textHerkese açık avatar1–1,000 karakter
voicetext ile herkese açık avatar102 addan biri
promptTümüEn fazla 1,200 karakter
aspect_ratioHerkese açık avatar16:9, 9:16, 1:1, 4:5, 5:4
resolutionTü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 codeerror.typeNe yapmalı
400validation_error ve diğerleriGirdiyi düzeltin: 2–60 s dışında ses, bilinmeyen avatar adı, başka bir moddan alan. Değiştirmeden yeniden denemeyin
401authentication_errorAuthorization: Bearer başlığını kontrol edin
402insufficient_credits_errorBakiye yükleyin veya çalışan metin görevlerinin hesaplaşmasını bekleyin (aşağıda)
429rate_limit_errorBekleyip yeniden deneyin
500 / 502 / 503internal_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):

Model1080p2K
heygen-avatar-6-turbo10 kredi ($0.05) / s18 kredi ($0.09) / s
heygen-avatar-620 kredi ($0.10) / s29 kredi ($0.145) / s
  • audio_url ile (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.
  • text ile: 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.

Share: