176 lines
5.4 KiB
Markdown
176 lines
5.4 KiB
Markdown
# SKILL.md — heygen-video
|
||
|
||
## Назначение
|
||
|
||
Генерация видеокружочков (video notes) в Telegram через HeyGen API. Аватарка Стрим "говорит" голосом ElevenLabs с синхронизацией губ через HeyGen.
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
Текст → ElevenLabs TTS → MP3 файл
|
||
↓
|
||
HeyGen Upload API (MP3 → audio_url)
|
||
↓
|
||
HeyGen Video API (talking_photo + audio → MP4)
|
||
↓
|
||
Poll Status → Download MP4
|
||
↓
|
||
FFmpeg (обрезать до 512×512)
|
||
↓
|
||
Telegram sendVideoNote
|
||
```
|
||
|
||
---
|
||
|
||
## Компоненты
|
||
|
||
### 1. ElevenLabs TTS API
|
||
- **Назначение:** генерация голоса из текста
|
||
- **Endpoint:** `https://api.elevenlabs.io/v1/text-to-speech/{voice_id}`
|
||
- **Голос:** `TPIitICAZ8CqlGZ81AKm` (голос Стрим)
|
||
- **Модель:** `eleven_multilingual_v2`
|
||
- **Выход:** MP3 файл
|
||
- **Ключ:** `ELEVENLABS_API_KEY` в `~/.openclaw/.env`
|
||
|
||
### 2. HeyGen Upload API
|
||
- **Endpoint:** `POST https://upload.heygen.com/v1/asset`
|
||
- **Header:** `X-API-Key: {key}`
|
||
- **Content-Type:** определяется по типу файла
|
||
- MP3: `audio/mpeg`
|
||
- JPG: `image/jpeg`
|
||
- **Body:** raw binary файл
|
||
- **Response:** `{"code": 100, "data": {"url": "https://resource2.heygen.ai/..."}}`
|
||
|
||
### 3. HeyGen Video Generate API
|
||
- **Endpoint:** `POST https://api.heygen.com/v2/video/generate`
|
||
- **Header:** `X-API-Key: {key}`, `Content-Type: application/json`
|
||
- **Body:**
|
||
```json
|
||
{
|
||
"video_inputs": [{
|
||
"character": {
|
||
"type": "talking_photo",
|
||
"talking_photo_id": "<TALKING_PHOTO_ID>"
|
||
},
|
||
"voice": {
|
||
"type": "audio",
|
||
"audio_url": "<MP3_URL от HeyGen>"
|
||
}
|
||
}]
|
||
}
|
||
```
|
||
- **Response:** `{"data": {"video_id": "<id>"}}`
|
||
|
||
### 4. HeyGen Video Status API (polling)
|
||
- **Endpoint:** `GET https://api.heygen.com/v1/video_status.get?video_id={id}`
|
||
- **Header:** `X-API-Key: {key}`
|
||
- **Response:**
|
||
- `{"data": {"status": "pending"}}` — ещё
|
||
- `{"data": {"status": "completed", "url": "https://..."}}` — готово
|
||
- `{"data": {"status": "failed"}}` — ошибка
|
||
- **Polling:** каждые 5 сек, max 300 сек (5 мин)
|
||
|
||
### 5. FFmpeg
|
||
- Конвертация MP4 в квадрат 512×512
|
||
- Путь: `/home/node/bin/ffmpeg-7.0.2-amd64-static/ffmpeg`
|
||
|
||
### 6. Telegram sendVideoNote API
|
||
- Отправка MP4 как video note
|
||
- Лимит: 512×512, до 60 сек, до 50MB
|
||
|
||
---
|
||
|
||
## Файлы
|
||
|
||
- `SKILL.md` — этот файл
|
||
- `scripts/generate_heygen_video.py` — основной скрипт генерации
|
||
- `scripts/send_heygen_video.sh` — shell-обёртка для отправки
|
||
|
||
---
|
||
|
||
## Переменные окружения (`~/.openclaw/.env`)
|
||
|
||
```
|
||
ELEVENLABS_API_KEY=<key>
|
||
HEYGEN_API_KEY=<key>
|
||
HEYGEN_TALKING_PHOTO_ID=<id>
|
||
```
|
||
|
||
---
|
||
|
||
## generate_heygen_video.py
|
||
|
||
**Использование:**
|
||
```bash
|
||
python3 generate_heygen_video.py "Текст для озвучки" [output_path]
|
||
```
|
||
|
||
**Параметры:**
|
||
- Аргумент 1: текст для озвучки (обязательно)
|
||
- Аргумент 2: путь для сохранения MP4 (опционально, по умолчанию `/tmp/heygen_video_{timestamp}.mp4`)
|
||
|
||
**Выход:** путь к MP4 файлу или error
|
||
|
||
**Шаги:**
|
||
1. Генерирует MP3 через ElevenLabs
|
||
2. Определяет длительность через ffprobe
|
||
3. Загружает MP3 в HeyGen
|
||
4. Создаёт видео через HeyGen API
|
||
5. Polling статуса каждые 5 сек
|
||
6. Скачивает готовый MP4
|
||
7. Конвертирует в 512×512 через FFmpeg
|
||
8. Сохраняет результат
|
||
|
||
**Обработка ошибок:**
|
||
- Если видео > 60 сек — обрезать
|
||
- Если файл > 50MB — логировать предупреждение
|
||
- Если HeyGen вернул ошибку — вывести код и сообщение
|
||
|
||
---
|
||
|
||
## send_heygen_video.sh
|
||
|
||
**Использование:**
|
||
```bash
|
||
./send_heygen_video.sh "Текст"
|
||
```
|
||
|
||
**Параметры:**
|
||
- Аргумент 1: текст (обязательно)
|
||
- BOT_TOKEN и CHAT_ID — из `~/.openclaw/.env` или аргументы
|
||
|
||
**Выход:** `message_id` в stdout
|
||
|
||
---
|
||
|
||
## Аватарка
|
||
|
||
`talking_photo_id` — ID обработанного talking photo в HeyGen. Создаётся один раз:
|
||
1. Загрузить фото в HeyGen
|
||
2. HeyGen обработает (1-2 мин)
|
||
3. Получить ID через API или интерфейс
|
||
4. Сохранить в `HEYGEN_TALKING_PHOTO_ID`
|
||
|
||
---
|
||
|
||
## Стоимость (актуально на 09.04.2026)
|
||
|
||
| Компонент | Цена |
|
||
|-----------|------|
|
||
| ElevenLabs TTS (10 сек) | ~$0.01 |
|
||
| HeyGen Avatar III (10 сек) | $0.17 |
|
||
| **Итого за 10 сек** | **~$0.18** |
|
||
|
||
vs VEED Fabric 480p: $0.86 (в 4.7 раза дешевле!)
|
||
|
||
---
|
||
|
||
## Ограничения
|
||
|
||
- Макс длительность: 60 сек (Telegram limit)
|
||
- Макс размер файла: 50MB
|
||
- HeyGen: max 30 сек на генерацию, но можно обрезать
|
||
- Фото: JPG/PNG, до 50MB, HeyGen сам оптимизирует
|