Heygen AI'yı API ile Kullanma: Eksiksiz Bir Kılavuz

Heygen AI, kullanıcıların gerçekçi yapay zeka tarafından oluşturulmuş avatar videolarını programlı bir şekilde oluşturmasını sağlayan güçlü bir platformdur. Bu kapsamlı eğitim, basit avatar videolarından karmaşık şablon tabanlı içerik oluşturmaya kadar çeşitli kullanım durumları için Heygen'in API'sini entegre etme ve kullanma sürecinde size rehberlik edecektir. Her bölüm, Heygen'in yeteneklerinde ustalaşmanıza yardımcı olmak için ayrıntılı adım adım talimatlar sağlar.

💡

API geliştirme iş akışınızı kolaylaştırmak mı istiyorsunuz? Apidog, API tasarımı, hata ayıklama, test etme ve dokümantasyon için kapsamlı bir araç takımı sunan, hepsi bir arada bir platformda, nihai Postman alternatifi olarak öne çıkıyor.

button

Sezgisel arayüzü, işbirliği özellikleri ve güçlü otomasyon yetenekleriyle Apidog, API kalitesini artırırken geliştirme süresini önemli ölçüde azaltır.

button

İster karmaşık bir mikro hizmet mimarisi oluşturuyor olun, ister Heygen gibi üçüncü taraf API'leriyle entegre olun, Apidog'un sahte sunucuları, ortam değişkenleri ve kapsamlı test seçenekleri, verimlilik ve güvenilirlik talep eden geliştiriciler için tercih edilen seçimdir. Apidog'u bugün deneyin ve API geliştirme araçlarında bir sonraki evrimi deneyimleyin.

button

Heygen API'ye Giriş

Heygen API, geliştiricilerin yapay zeka destekli avatar videolarını programlı bir şekilde oluşturmasına ve Heygen'in yeteneklerini uygulamalarına entegre etmesine olanak tanır. API, video oluşturma, çeviri ve şablon tabanlı içerik oluşturma dahil olmak üzere çeşitli özellikler sunar. Bu eğitimi takip ederek, pazarlama, eğitim, müşteri hizmetleri ve daha fazlası için ilgi çekici içerikler oluşturmak üzere bu yeteneklerden nasıl yararlanacağınızı öğreneceksiniz.

API'nin temel işlevselliği, sağladığınız herhangi bir metni konuşabilen veya ses dosyalarıyla senkronize olabilen gerçekçi yapay zeka avatarlarıyla videolar oluşturmak etrafında döner. Ek olarak, arka planları özelleştirebilir, videoları birden fazla dile çevirebilir ve daha karmaşık yapımlar için şablonlarla çalışabilirsiniz.

Heygen'in API'si, temel videolar oluşturmanın ötesinde, kullanıcılarınız için otomatik olarak kişiselleştirilmiş içerik oluşturabilen, etkileşimli deneyimler yaratabilen ve hatta mevcut videoları birden fazla dile çevirebilen gelişmiş uygulamalar oluşturmanıza olanak tanır. Bu, küresel işletmeler, içerik oluşturucular, eğitimciler ve yapay zeka tarafından oluşturulan videoyu ürünlerine dahil etmek isteyen geliştiriciler için paha biçilmez hale getirir.

Heygen API'ye Başlarken

Heygen API için Hesap Oluşturma

Heygen hesabınızı oluşturmak için şu adımları izleyin:

Heygen'in resmi web sitesini ziyaret edin heygen website.
Sağ üst köşedeki "Kaydol" veya "Başlayın" düğmesini tıklayın
Tercih ettiğiniz kaydolma yöntemini seçin (e-posta, Google vb.)
Kayıt formunu bilgilerinizi girerek tamamlayın
Şartları ve gizlilik politikasını kabul edin
Gerekirse e-posta adresinizi doğrulayın
Yeni hesabınıza giriş yapın

Kayıttan sonra, hem Heygen'in web arayüzüne hem de API yeteneklerine erişebileceksiniz. Yeni kullanıcılar genellikle sınırlı özelliklere sahip ücretsiz bir deneme sürümü alır. Ücretsiz deneme sürümü, filigranlı videolar ve sınırlı kullanım kotaları içerir, ancak ücretli bir plana geçmeden önce API işlevselliğini test etmek için yeterlidir.

Kayıt işlemi sırasında, Heygen amaçlanan kullanım durumunuzu sorabilir. Bu bilgileri sağlamak, Heygen'in özel ihtiyaçlarınız için önerileri uyarlamasına yardımcı olabilir, ancak API erişimi için kesinlikle gerekli değildir.

API Anahtarınızı Alma

API'ye erişmek için, API anahtarınızı almak üzere bu ayrıntılı adımları izleyin:

Heygen hesabınıza giriş yapın
Sağ üst köşedeki profil resminizi veya avatarınızı tıklayın
Açılır menüden "Ayarlar"ı seçin
"Abonelikler" sekmesine gidin
"HeyGen API" bölümüne gidin
"API Jetonu"nun yanındaki "Göster"i tıklayın
İstenirse kimlik doğrulama yapın
İsteklerinizde kullanmak üzere API jetonunuzu kopyalayın

Bu jetonu güvende tutun, çünkü hesabınız altında API'ye tam erişim sağlar. Bunu asla istemci tarafı kodunda veya genel depolarda ifşa etmeyin. API anahtarınızın tehlikeye girdiğinden şüpheleniyorsanız, aynı ayarlar sayfasından yenisini oluşturabilirsiniz.

API anahtarınız, Heygen API'sine yaptığınız tüm isteklerde kullanılacaktır. Genellikle, bunu HTTP isteklerinizin X-Api-Key başlığına dahil edersiniz. Örneğin:

X-Api-Key: your-api-key-here

Farklı abonelik katmanları farklı API kullanım sınırları sunar. Ücretsiz Deneme, filigranlı videolarla temel erişim sağlarken, ücretli planlar (Pro, Scale ve Enterprise) artan kullanım sınırları, özellikler ve kalite seçenekleri sunar. Plan özellikleri ve sınırlamaları hakkında en güncel bilgiler için Heygen'in fiyatlandırma sayfasını kontrol edin.

Heygen API ile Temel Avatar Video Oluşturma

Heygen API ile Mevcut Avatarları Listeleme

Video oluşturmaya başlamak için, hangi avatarların mevcut olduğunu bilmeniz gerekir. Şu adımları izleyin:

Terminalinizi veya API istemcinizi açın
Şu isteği yapın:

curl --request GET \\\\
  --url <https://api.heygen.com/v2/avatars> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Şuna benzeyecek olan yanıtı inceleyin:

{
  "error": null,
  "data": {
    "avatars": [
      {
        "avatar_id": "Angela-inblackskirt-20220820",
        "avatar_name": "Angela in Black Dress",
        "gender": "female",
        "preview_image_url": "<preview_image_url>",
        "preview_video_url": "<preview_video_url>"
      },
      // More avatars...
    ]
  }
}

Bir avatar seçin ve daha sonra kullanmak üzere avatar_id'sini not edin

Her avatarın farklı görünümleri ve stilleri vardır. Bazı avatarlar, iş sunumları, gündelik sohbetler veya eğitim içeriği gibi belirli bağlamlar için tasarlanmıştır. Amacınıza uygun birini bulmak için sağlanan URL'leri kullanarak avatarları önizleyin.

Python kullanıyorsanız, bunun yerine bu kod parçasını kullanabilirsiniz:

import requests

headers = {
    'Accept': 'application/json',
    'X-Api-Key': 'your-api-key'
}

response = requests.get('<https://api.heygen.com/v2/avatars>', headers=headers)
avatars = response.json()['data']['avatars']

# Print all available avatars
for avatar in avatars:
    print(f"ID: {avatar['avatar_id']}, Name: {avatar['avatar_name']}")

Avatarların "normal" veya "gündelik" gibi farklı stilleri vardır. Varsayılan stil "normal"dir, ancak avatar birden fazla stili destekliyorsa video oluştururken başkalarını belirtebilirsiniz.

Heygen API ile Mevcut Sesleri Listeleme

Ardından, avatarınız için bir ses seçmeniz gerekir. Şu adımları izleyin:

Şu API isteğini yapın:

curl --request GET \\\\
  --url <https://api.heygen.com/v2/voices> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Mevcut sesleri bulmak için yanıtı inceleyin:

{
  "error": null,
  "data": {
    "voices": [
      {
        "voice_id": "26b2064088674c80b1e5fc5ab1a068ec",
        "language": "English",
        "gender": "male",
        "name": "Rex",
        "preview_audio": "<https://resource.heygen.ai/text_to_speech/bCo7SFtTvcJz6udLqHmUKf.mp3>",
        "support_pause": false,
        "emotion_support": true,
        "support_interactive_avatar": true
      },
      // More voices...
    ]
  }
}

Bir ses seçin ve daha sonra kullanmak üzere voice_id'sini not edin

Sesler çeşitli dillerde, aksanlarda ve cinsiyetlerde gelir. Projenizin tonuna ve stiline uygun bir ses bulmak için önizleme sesini dinleyin. Bazı sesler, daha dinamik sunumlar için yararlı olabilecek duygusal tonlamalar veya duraklamalar gibi ek özellikleri destekler.

Daha sonra etkileşimli avatarlar kullanmayı planlıyorsanız, tüm sesler bu özelliği desteklemediğinden support_interactive_avatar özelliğine dikkat edin.

Python eşdeğeri:

response = requests.get('<https://api.heygen.com/v2/voices>', headers=headers)
voices = response.json()['data']['voices']

# Print all available voices
for voice in voices:
    print(f"ID: {voice['voice_id']}, Name: {voice['name']}, Language: {voice['language']}")

# Filter for English voices only
english_voices = [v for v in voices if v['language'] == 'English']
print(f"Found {len(english_voices)} English voices")

Heygen API ile Basit Bir Avatar Videosu Oluşturma

Artık bir avatar ve ses seçtiğinize göre, bir video oluşturmak için şu adımları izleyin:

Seçilen avatar ve ses ile istek yükünüzü hazırlayın:

{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "Angela-inTshirt-20220820",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "Welcome to the HeyGen API! This is a demonstration of how easy it is to create engaging avatar videos programmatically.",
        "voice_id": "1bd001e7e50f421d891986aad5158bc8",
        "speed": 1.1
      },
      "background": {
        "type": "color",
        "value": "#87CEEB"
      }
    }
  ],
  "dimension": {
    "width": 1280,
    "height": 720
  }
}

Videoyu oluşturmak için isteği gönderin:

curl -X POST <https://api.heygen.com/v2/video/generate> \\\\
-H 'X-Api-Key: <your-api-key>' \\\\
-H 'Content-Type: application/json' \\\\
-d '<your-prepared-json>'

Yanıtından video_id'yi kaydedin:

{
  "error": null,
  "data": {
    "video_id": "abcdef123456"
  }
}

İstek parametrelerini inceleyelim:

video_inputs: Bir sahne yapılandırmaları dizisi
character: Kullanılacak avatarı belirtir
type: Standart Heygen avatarları için "avatar"
avatar_id: Seçtiğiniz avatarın kimliği
avatar_style: Avatarın görsel stili (örneğin, "normal", "gündelik")
voice: Konuşma için yapılandırma
type: Metin okuma dönüşümü için "text"
input_text: Avatarın konuşacağı senaryo
voice_id: Seçtiğiniz sesin kimliği
speed: Konuşma hızı (1.0 normaldir, daha yüksek daha hızlıdır)
background: Arka plan yapılandırması
type: Düz renk arka planlar için "color"
value: Onaltılık renk kodu
dimension: Çıktı video boyutları
width: Piksel cinsinden video genişliği
height: Piksel cinsinden video yüksekliği

Videolarınızı özelleştirmek için bu parametreleri ayarlayabilirsiniz. Örneğin, speed değerini değiştirmek avatarın ne kadar hızlı konuştuğunu etkilerken, dimension video çözünürlüğünü kontrol eder.

Python uygulaması:

import json
import requests

payload = {
    "video_inputs": [
        {
            "character": {
                "type": "avatar",
                "avatar_id": "Angela-inTshirt-20220820",
                "avatar_style": "normal"
            },
            "voice": {
                "type": "text",
                "input_text": "Welcome to the HeyGen API! This is a demonstration of how easy it is to create engaging avatar videos programmatically.",
                "voice_id": "1bd001e7e50f421d891986aad5158bc8",
                "speed": 1.1
            },
            "background": {
                "type": "color",
                "value": "#87CEEB"
            }
        }
    ],
    "dimension": {
        "width": 1280,
        "height": 720
    }
}

response = requests.post(
    '<https://api.heygen.com/v2/video/generate>',
    headers={
        'X-Api-Key': 'your-api-key',
        'Content-Type': 'application/json'
    },
    data=json.dumps(payload)
)

video_id = response.json()['data']['video_id']
print(f"Video generation initiated! Video ID: {video_id}")

Heygen API ile Video Oluşturma Durumunu Kontrol Etme

Video oluşturmayı başlattıktan sonra, durumunu kontrol etmek için şu adımları izleyin:

Durum kontrolü isteği yapmak için önceki adımdan video_id'yi kullanın:

curl --request GET \\\\
  --url <https://api.heygen.com/v1/video_status.get?video_id=><video_id> \\\\
  --header 'Accept: application/json' \\\\
  --header 'X-Api-Key: <your-api-key>'

Yanıtındaki durumu izleyin:

{
  "code": 100,
  "data": {
    "id": "<id>",
    "status": "processing",
    "thumbnail_url": null,
    "video_url": null,
    "caption_url": null,
    "gif_url": null,
    "error": null,
    "duration": null,
    "callback_id": null,
    "video_url_caption": null
  },
  "message": "Success"
}

Durum "completed" veya "failed" olarak değişene kadar kontrolü tekrarlayın

Video oluşturma genellikle şunlara bağlı olarak 30 saniye ile birkaç dakika arasında sürer:

Girdi metninin uzunluğu
Sunucu yükü
Video karmaşıklığı
Abonelik katmanınız

Karşılaşabileceğiniz durum değerleri:

pending: İsteğiniz alındı ancak işleme henüz başlanmadı
processing: Videonuz şu anda oluşturuluyor
completed: Videonuz indirilmeye hazır
failed: Videonuzu oluştururken bir hata oluştu

Bir video başarısız olduğunda, yanıt sorunu açıklayan bir hata mesajı içerecektir:

{
  "code": 100,
  "data": {
    "id": "<id>",
    "status": "failed",
    "error": {
      "code": 40119,
      "message": "Video is too long",
      "detail": "Video is too long (> 3600.0s). Please upgrade your plan to generate longer videos"
    },
    "thumbnail_url": null,
    "video_url": null,
    "caption_url": null,
    "gif_url": null,
    "duration": null,
    "callback_id": null,
    "video_url_caption": null
  },
  "message": "Success"
}

Python uygulaması ile yoklama:

import time
import requests

def check_video_status(video_id, api_key):
    headers = {
        'Accept': 'application/json',
        'X-Api-Key': api_key
    }

    max_attempts = 30  # Avoid infinite loops
    attempt = 0

    while attempt < max_attempts:
        response = requests.get(
            f'<https://api.heygen.com/v1/video_status.get?video_id={video_id}>',
            headers=headers
        )

        data = response.json()['data']
        status = data['status']

        if status == 'completed':
            print("Video generation complete!")
            return {
                'video_url': data['video_url'],
                'thumbnail_url': data['thumbnail_url'],
                'duration': data['duration']
            }
        elif status == 'failed':
            error = data['error']
            print(f"Video generation failed: {error}")
            return None
        else:
            print(f"Video status: {status}. Checking again in 5 seconds...")
            attempt += 1
            time.sleep(5)

    print("Maximum attempts reached. Video still not ready.")
    return None

# Usage
result = check_video_status("abcdef123456", "your-api-key")
if result:
    print(f"Video URL: {result['video_url']}")
    print(f"Duration: {result['duration']} seconds")

Heygen API ile Oluşturduğunuz Videoyu İndirme

Video durumu "completed" olduğunda, videonuzu indirmek için şu adımları izleyin:

Durum yanıtından video_url'yi çıkarın
URL'yi kullanarak videoyu indirin:

curl <video_url> --output my_avatar_video.mp4

İndirilen dosyanın doğru çalıştığını doğrulayın

Python uygulaması:

import requests

def download_video(video_url, output_filename="my_avatar_video.mp4"):
    response = requests.get(video_url)

    if response.status_code == 200:
        with open(output_filename, 'wb') as file:
            file.write(response.content)

        print(f"Video downloaded successfully to {output_filename}")
        print(f"File size: {len(response.content) / (1024 * 1024):.2f} MB")
        return True
    else:
        print(f"Failed to download video. Status code: {response.status_code}")
        return False

# Usage
success = download_video("<https://storage.googleapis.com/heygen-videos/>...")

Önemli Not: Video URL'si 7 gün sonra sona erer. Videonuzu süresi dolmadan indirdiğinizden veya gerektiğinde videoyu yeniden oluşturmak veya yeniden almak için bir sistem uyguladığınızdan emin olun.

Üretim sistemleri için şunları göz önünde bulundurun:

Oluşturulduktan hemen sonra videoları indirmek için zamanlanmış bir iş ayarlama
Uzun süreli erişim için videoları kendi bulut depolama alanınızda saklama
Video kimliklerini, oluşturma tarihlerini ve son kullanma tarihlerini izlemek için bir veritabanı uygulama

Heygen API: Şablonlarla Çalışmak

Şablonlar, basit avatar videolardan daha fazla esneklik sunarak, önceden tasarlanmış bir düzende metinleri, görüntüleri, videoları, sesleri ve avatarları özelleştirmenize olanak tanır.

Heygen API Şablonları ve Basit Avatar Videoları

İşte temel farklılıkların karşılaştırması:

Avatar Videoları:

Yalnızca bir avatarın konuşmasına odaklanır
Tek bir avatarla sınırlı
Basit arka plan seçenekleri
Doğrudan konuşan kafa videoları için en iyisi
Tamamen API çağrıları aracılığıyla oluşturulur

Şablon Videoları:

Çeşitli öğelerle birden fazla sahne
Metin, resim, video, avatar ve ses için özelleştirilebilir yer tutucular
Karmaşık geçişler ve animasyonlar
Tek bir videoda birden fazla avatar desteği
Şablonlar Heygen web arayüzü aracılığıyla oluşturulur
API, şablonlara dayalı videolar oluşturmak için kullanılır

Şablonlar, tutarlı video serileri oluşturmak veya kişiselleştirilmiş videoları ölçeklendirmek için özellikle kullanışlıdır. Örneğin, ürün tanıtımları için bir şablon oluşturabilir ve ardından yalnızca ilgili metinleri, görüntüleri ve ürün ayrıntılarını değiştirerek farklı ürünler için özel sürümler oluşturabilirsiniz.

Heygen API Yer Tutucularla Şablon Oluşturma

Şablonlar Heygen web arayüzü aracılığıyla oluşturulur:

Heygen hesabınıza giriş yapın
Şablonlar bölümüne gidin
"Şablon Oluştur"u tıklayın
Şu bileşenlerle şablonunuzu tasarlamak için düzenleyiciyi kullanın:

Metin öğeleri: Daha sonra özelleştirilebilen metinler ekleyin
Avatar sahneleri: Özelleştirilebilir içerik konuşacak avatarlar ekleyin
Görüntü yer tutucuları: Özel görüntüler için alanlar ekleyin
Video yer tutucuları: Özel video klipleri için alanlar ekleyin
Ses öğeleri: Arka plan müziği veya ses efektleri ekleyin

Özelleştirilebilir hale getirmek istediğiniz her öğe için, çift süslü parantez kullanarak bir yer tutucu tanımlayın:

Metin örneği: {{product_name}}
Avatar senaryosu örneği: {{product_description}}
Görüntü yer tutucu: Bir görüntü seçin ve değişken olarak işaretleyin

Öğeleri istediğiniz gibi düzenleyin ve şablonu önizleyin
Şablonunuzu açıklayıcı bir adla kaydedin

Örneğin, bir ürün duyurusu şablonu oluşturuyorsanız, şunları ekleyebilirsiniz:

{{company_name}} ve {{product_name}} ile bir açılış metni
"{{product_name}}'i tanıtmaktan heyecan duyuyoruz, {{key_benefit}} sunuyor" diyen bir avatar
{{product_image}} için bir yer tutucu görüntü
Değiştirilebilen arka plan müziği

Yer tutucular farklı türlerde olabilir:

Metin: Yazılı metinleri veya avatar senaryolarını değiştirmek için
Görüntü: Görüntü öğelerini değiştirmek için
Video: Video klipleri değiştirmek için
Avatar: Hangi avatarın görüneceğini değiştirmek için
Ses: Arka plan müziğini veya ses efektlerini değiştirmek için

Heygen API ile Şablonlarınızı Listeleme

Oluşturduğunuz tüm şablonları almak için:

curl --location '<https://api.heygen.com/v2/templates>' \\\\
  --header 'accept: application/json' \\\\
  --header 'x-api-key: <your-api-key>'

Bu, kimlikleri ve küçük resim URL'leri dahil olmak üzere tüm şablonlarınız hakkında bilgi döndürür:

{
  "error": null,
  "data": {
    "templates": [
      {
        "template_id": "abcdef123456",
        "title": "Product Announcement",
        "thumbnail_url": "<https://storage.googleapis.com/heygen-templates/thumbnails/>...",
        "created_at": "2023-09-15T14:25:30Z"
      },
      {
        "template_id": "ghijkl789012",
        "title": "Weekly Update",
        "thumbnail_url": "<https://storage.googleapis.com/heygen-templates/thumbnails/>...",
        "created_at": "2023-09-18T09:12:45Z"
      }
    ]
  }
}

Python uygulaması:

import requests

headers = {
    'accept': 'application/json',
    'x-api-key': 'your-api-key'
}

response = requests.get('<https://api.heygen.com/v2/templates>', headers=headers)
templates = response.json()['data']['templates']

print(f"Found {len(templates)} templates:")
for template in templates:
    print(f"ID: {template['template_id']}, Title: {template['title']}, Created: {template['created_at']}")

Heygen API ile Şablon Öğelerini Alma

Belirli bir şablonda bulunan değişkenleri görmek için:

curl --location '<https://api.heygen.com/v2/template/><template_id>' \\\\
  --header 'accept: application/json' \\\\
  --header 'x-api-key: <your-api-key>'

Bu, şablonunuzdaki tüm özelleştirilebilir öğeleri gösterir:

{
  "error": null,
  "data": {
    "template_id": "abcdef123456",
    "title": "Product Announcement",
    "variables": {
      "company_name": {
        "name": "company_name",
        "type": "text",
        "properties": {
          "default_content": "Company Name"
        }
      },
      "product_name": {
        "name": "product_name",
        "type": "text",
        "properties": {
          "default_content": "Product Name"
        }
      },
      "key_benefit": {
        "name": "key_benefit",
        "type": "text",
        "properties": {
          "default_content": "amazing benefits to users"
        }
      },
      "product_image": {
        "name": "product_image",
        "type": "image",
        "properties": {
          "default_url": "<https://example.com/default-image.jpg>"
        }
      }
    }
  }
}

Şablonunuzun değişkenlerinin yapısını anlamak, videoları doğru bir şekilde oluşturmak için çok önemlidir. Her değişkenin türünü (metin, görüntü, video vb.) ve sağlanan varsayılan değerleri not edin.

Python uygulaması:

def get_template_details(template_id, api_key):
    headers = {
        'accept': 'application/json',
        'x-api-key': api_key
    }

    response = requests.get(
        f'<https://api.heygen.com/v2/template/{template_id}>',
        headers=headers
    )

    if response.status_code == 200:
        template = response.json()['data']
        variables = template['variables']

        print(f"Template: {template['