--- pageType: source id: source.tz title: TZ sourceType: local-file sourcePath: /home/node/.openclaw/workspace/tasks/video-notes/TZ.md ingestedAt: 2026-04-10T13:36:51.302Z updatedAt: 2026-04-10T13:36:51.302Z status: active --- # TZ ## Source - Type: `local-file` - Path: `/home/node/.openclaw/workspace/tasks/video-notes/TZ.md` - Bytes: 8806 - Updated: 2026-04-10T13:36:51.302Z ## Content ````text # ТЗ: Видеокружочки в Telegram (lip sync) ## Общее описание Система генерации и отправки анимированных видеокружочков (video notes) в Telegram. Аватарка «говорит» голосом ElevenLabs с синхронизацией губ через VEED Fabric 1.0. --- ## Архитектура ``` Пользователь → Текст → send_video_note.sh → Telegram кружочек │ ├── Шаг 1: ElevenLabs TTS (текст → MP3) ├── Шаг 2: fal.ai Upload (фото + MP3 → URLs) ├── Шаг 3: VEED Fabric 1.0 (фото + MP3 → MP4 с lip sync) ├── Шаг 4: FFmpeg (MP4 → 512×512 квадрат) └── Шаг 5: Telegram sendVideoNote (MP4 → кружочек) ``` --- ## Компоненты ### 1. ElevenLabs TTS API - **Назначение:** генерация голоса из текста - **Endpoint:** `https://api.elevenlabs.io/v1/text-to-speech/{voice_id}` - **Голос:** `TPIitICAZ8CqlGZ81AKm` (голос Стрим) - **Модель:** `eleven_multilingual_v2` - **Вход:** текст (до 5000 символов) - **Выход:** MP3 файл - **Ключ:** `ELEVENLABS_API_KEY` в `~/.openclaw/.env` ### 2. fal.ai Upload API - **Назначение:** загрузка файлов на storage fal.ai - **Endpoint:** `https://gateway.fal.ai/storage/upload` - **Аутентификация:** `Authorization: Key {key_id}:{key_secret}` - **Вход:** файл (изображение или аудио) - **Выход:** публичный URL файла на fal.ai storage - **Ключ:** `FAL_KEY` в `~/.openclaw/.env` (формат: `key_id:key_secret`) - **Fallback:** если upload не работает — кодирование в base64 и передача как data URL ### 3. VEED Fabric 1.0 API (fal.ai) - **Назначение:** генерация видео с lip sync из фото и аудио - **Endpoint:** `https://queue.fal.run/veed/fabric-1.0` - **Аутентификация:** `Authorization: Key {key_id}:{key_secret}` - **Вход:** - `image_url` — URL фото аватарки (или base64 data URL) - `audio_url` — URL MP3 файла с голосом (или base64 data URL) - `resolution` — разрешение видео (`"720p"` или `"480p"`) - **Выход:** JSON с URL готового MP4 видео - **Архитектура:** асинхронная (queue + poll) 1. POST → получает `request_id` + статус `IN_QUEUE` 2. GET poll → статусы: `IN_QUEUE` → `IN_PROGRESS` → `COMPLETED` 3. GET result → URL MP4 файла - **Таймаут:** 300 секунд (5 минут) - **Стоимость:** ~$0.40 за минуту видео ### 4. FFmpeg - **Назначение:** конвертация видео в квадрат 512×512 - **Путь:** `/home/node/bin/ffmpeg-7.0.2-amd64-static/ffmpeg` - **Операции:** - Масштабирование до 512×512 с обрезкой по центру - Конвертация в MP4 (H.264) - Округление длительности до целых секунд ### 5. Telegram sendVideoNote API - **Назначение:** отправка кружочка в Telegram - **Endpoint:** `https://api.telegram.org/bot{token}/sendVideoNote` - **Параметры:** - `chat_id` — ID чата получателя - `video_note` — MP4 файл - `length` — размер кружочка (512 пикселей) - `duration` — длительность в секундах - **Токен бота:** читается из `~/.openclaw/openclaw.json` --- ## Скрипт: send_video_note.sh **Расположение:** `/home/node/.openclaw/workspace/scripts/send_video_note.sh` **Использование:** ```bash ./send_video_note.sh "Текст для озвучки" ./send_video_note.sh "Текст" [VOICE_ID] [CHAT_ID] ``` **Параметры:** - `Текст` — текст для озвучки (обязательный) - `VOICE_ID` — ID голоса ElevenLabs (по умолчанию: `TPIitICAZ8CqlGZ81AKm`) - `CHAT_ID` — ID Telegram чата (по умолчанию: `126472752`) **Зависимости:** - curl - python3 - ffmpeg (статический, путь в переменной `FFMPEG_BIN`) - Переменные в `~/.openclaw/.env`: `ELEVENLABS_API_KEY`, `FAL_KEY` **Временные файлы:** - Все промежуточные файлы создаются в `/tmp/video_note_*` - Автоматически удаляются после завершения --- ## Pipeline (подробно) ### Шаг 1: Генерация голоса (ElevenLabs TTS) ``` POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id} Headers: xi-api-key, Content-Type: application/json Body: {"text": "...", "model_id": "eleven_multilingual_v2"} Output: MP3 файл ``` ### Шаг 2: Определение длительности аудио ``` ffprobe -v error -show_entries format=duration -of csv=p=0 tts.mp3 Output: длительность в секундах (float) ``` ### Шаг 3: Загрузка файлов на fal.ai ``` POST https://gateway.fal.ai/storage/upload Headers: Authorization: Key {key_id}:{key_secret}, Content-Type: application/octet-stream Body: бинарные данные файла Output: {"file_url": "https://..."} ``` Для каждого файла: аватарка (JPG) и аудио (MP3). ### Шаг 4: Отправка задачи VEED Fabric 1.0 ``` POST https://queue.fal.run/veed/fabric-1.0 Headers: Authorization: Key {key_id}:{key_secret}, Content-Type: application/json Body: {"image_url": "...", "audio_url": "...", "resolution": "480p"} Output: {"request_id": "...", "status": "IN_QUEUE"} ``` ### Шаг 5: Ожидание результата (poll) ``` GET https://queue.fal.run/veed/fabric-10/requests/{request_id}/status Headers: Authorization: Key {key_id}:{key_secret} Цикл: каждые 5 секунд, до 300 секунд Статусы: IN_QUEUE → IN_PROGRESS → COMPLETED ``` ### Шаг 6: Получение результата ``` GET https://queue.fal.run/veed/fabric-1.0/requests/{request_id} Headers: Authorization: Key {key_id}:{key_secret} Output: {"video": {"url": "https://v3b.fal.media/..."}} ``` ### Шаг 7: Скачивание видео ``` curl -L -o lipsync_raw.mp4 "{video_url}" ``` ### Шаг 8: Конвертация в квадрат 512×512 ``` ffmpeg -i lipsync_raw.mp4 \ -vf "crop='min(iw,ih)':'min(iw,ih)',scale=512:512" \ -c:v libx264 -preset fast -crf 23 \ -an -t {duration} -y video_note.mp4 ``` ### Шаг 9: Отправка в Telegram ``` POST https://api.telegram.org/bot{token}/sendVideoNote Body (multipart): - chat_id: 126472752 - video_note: @video_note.mp4 - length: 512 - duration: {duration_int} ``` --- ## Аватарка **Расположение:** `/home/node/.openclaw/workspace/data/avatars/stream-avatar.jpg` **Требования к аватарке:** - Формат: JPG или PNG - Лицо: анфас, хорошо видно - Размер: не менее 512×512 пикселей - Фон: нейтральный или любой **Для смены аватарки:** заменить файл `stream-avatar.jpg` --- ## Ограничения - **Длительность:** до 60 секунд (лимит Telegram video note) - **Размер:** до 50 МБ (лимит Telegram) - **Стоимость VEED:** ~$0.40 за минуту видео - **Стоимость ElevenLabs:** зависит от тарифа (символы) - **Время обработки:** ~80 секунд на 8 секунд видео (VEED Fabric 1.0) - **Разрешение:** 512×512 (квадрат, как требует Telegram) --- ## Интеграция в OpenClaw **Через Стрим (координатор):** - Стрим вызывает скрипт через `exec`: `send_video_note.sh "текст"` - Или передаёт задачу Dev-агенту через `sessions_spawn` **Через Dev-агента:** - Dev может вызывать скрипт из любого проекта - Передаёт текст и получает отправленный кружочек **Стоимость за вызов:** - ElevenLabs TTS: ~$0.01–0.03 за 10 секунд голоса - VEED Fabric 1.0: ~$0.07 за 10 секунд видео - **Итого: ~$0.10 за один кружочек** ```` ## Notes ## Related ### Referenced By - [Видеокружочки](entities/project-video-notes.md)