# 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 сам оптимизирует