Kandinsky

Генерирует и редактирует медиа через Kandinsky: рисует изображения по описанию, перерисовывает и правит существующие картинки, повышает разрешение и качество, создаёт короткие видео по тексту или из фотографии, оживляет изображения и делает говорящие аватары из фото и аудио. Используй всякий раз, когда пользователь хочет создать или изменить визуальный контент — «нарисуй», «сгенерируй картинку», «сделай логотип, иллюстрацию, обои, постер, открытку, иконку, стикер, мем или аватарку», «перерисуй, поправь или отфотошопь фото», «дорисуй», «убери или замени фон», «замени лицо», «улучши качество, увеличь, апскейл», «сделай видео», «оживи картинку», «заставь фото говорить», «липсинк», «озвучь аватар» — даже если слово «Kandinsky» не прозвучало. Различай: «аватарка» как картинка профиля — это обычная генерация изображения (t2i), а «говорящий аватар» из фото и аудио — это avatar. Не для поиска готовых картинок в интернете, распознавания и описания фото, построения графиков по данным.

Kandinsky — картинки и видео

Генерация и редактирование медиа через Kandinsky API: изображения (K6), короткие видео (K5) и говорящие аватары (GigaAvatar).

Вся работа идёт через один скрипт — scripts/kandinsky.py: нужен python3, дальше только стандартная библиотека, без зависимостей. Сам скрипт ничего не запускает — только HTTP-запросы к инстансу и запись готового файла.

Setup

Нужны две переменные окружения, обе обязательные:

• KANDINSKY_API_BASE — адрес выданного вам инстанса, вида http://ваш-сервер:5051. Значения по умолчанию нет: без него не будет ни одного запроса;
• KANDINSKY_API_KEY — ключ к этому инстансу.

Необязательная третья — KANDINSKY_OUT_DIR: каталог, куда складывать готовые файлы. Если её не задать, файлы лягут в служебный каталог навыка, а при запуске из оболочки — в текущий каталог.

Если чего-то не хватает, скрипт скажет об этом первой же командой. Если у пользователя нет адреса или ключа — подскажи, что запросить доступ можно письмом на [e-mail]. Ничего не подставляй от себя.

Проверить настройки, не тратя генерацию: python3 scripts/kandinsky.py health.

Usage

Куда попадёт файл, решает не -o, а скрипт. Разрешены только каталог из KANDINSKY_OUT_DIR и служебный каталог навыка (вне хоста — текущий каталог). Имя в -o можно не указывать вовсе, относительное имя ляжет в разрешённый каталог, а путь наружу скрипт отклонит с ошибкой. Готовый путь всегда есть в последней строке вывода: Готово: <файл> — её и бери, не додумывай путь сам.

bash

# текст → картинка
python3 scripts/kandinsky.py t2i "закат в горах, кинематографично" -o sunset.png
python3 scripts/kandinsky.py t2i "портрет" --resolution 768x1280 -o portrait.png

# картинка + текст → изменённая картинка
python3 scripts/kandinsky.py i2i in.png "в стиле акварели" -o edited.png

# апскейл ×2 / ×4
python3 scripts/kandinsky.py superres in.png --upscale 2 -o big.png

# текст → видео (--pro: качественнее и дольше)
python3 scripts/kandinsky.py t2v "волны на берегу" -o clip.mp4
python3 scripts/kandinsky.py t2v "волны на берегу" --pro -o clip.mp4

# оживить картинку: картинка → видео
python3 scripts/kandinsky.py i2v in.png "кот машет лапой" --quality hd -o clip.mp4

# фото + аудио → говорящий аватар
python3 scripts/kandinsky.py avatar face.png speech.wav -o avatar.mp4

# долгие задачи
python3 scripts/kandinsky.py status <task_id>
python3 scripts/kandinsky.py result <task_id> -o out.mp4

Разрешения: t2i — 1024x1024 (по умолчанию), 768x768, 768x1280, 1280x768, auto. t2v lite — 512x512, 512x768, 768x512; t2v --pro — 768x1280, 1280x768. У i2v вместо разрешения --quality lite|sd|hd.

Все команды печатают ход выполнения в stderr и Готово: <файл> в stdout; --quiet убирает первое. Показывай пользователю готовый файл, а не base64 и не содержимое ответа.

Промпт: пиши на русском или английском, описывай сцену, свет, ракурс и стиль; для i2v промпт должен описывать движение объекта, а не только камеру. Подробнее — references/prompting.md, схема API — references/api-cheatsheet.md.

Если навык установлен в Ouroboros

Из вкладки ClawHub навык ставится как type: script, и агент запускает его не в оболочке, а инструментом skill_exec:

text

skill_exec(skill="kandinsky-skill", script="scripts/kandinsky.py",
           args=["t2i", "закат в горах, кинематографично", "-o", "sunset.png"])

• аргументы идут массивом, оболочки нет: $ПЕРЕМЕННАЯ, ~, * и | не раскроются;
• адрес и ключ бери только из настроек навыка — платформа сама положит KANDINSKY_API_BASE и KANDINSKY_API_KEY в окружение процесса;
• путь результата не выдумывай: имени файла достаточно, каталог выберет скрипт (KANDINSKY_OUT_DIR из настроек, иначе служебный каталог навыка). Полный путь придёт последней строкой вывода — Готово: <файл>;
• предел одного запуска — 300 с, скрипт сам укладывается в 240 с и отдаёт понятную ошибку вместо обрыва. Видео и аватар могут не успеть: task_id виден в выводе, результат забирается отдельным вызовом result <task_id> -o out.mp4;
• показать картинку или видео пользователю должен сам агент: скриптовая версия в чат ничего не отправляет, она только сохраняет файл.

Security model

• Ключ — секрет: не печатай его, не подставляй в URL, не пиши в логи и файлы.
• Транспорт: по умолчанию plain http:// на публичный адрес запрещён — ключ ушёл бы открытым текстом. Разрешены HTTPS, loopback и приватные адреса. Осознанно обойти: --allow-insecure или KANDINSKY_ALLOW_INSECURE=1, но сначала предупреди пользователя.
• Фильтр контента включён.
• Скрипт читает ровно те файлы, которые указаны в аргументах. Ничего не сканирует и никуда больше не ходит.
• Запись ограничена кодом, а не уговором: файл попадёт только в KANDINSKY_OUT_DIR или в служебный каталог навыка (вне хоста — в текущий каталог). Путь проверяется по реальному (realpath), поэтому ни .., ни симлинк наружу не проходят.
• Подпроцессов скрипт не запускает: только HTTP и файловый ввод-вывод.

Limits

• Генерация асинхронная: скрипт сам ждёт результат. Видео и аватар — минуты.
• Задача может застрять в очереди (чаще всего superres) — скрипт не ждёт бесконечно, а сообщает об этом; task_id виден в выводе, результат можно забрать позже командой result.
• Ответ больше 200 МБ обрывается — защита от сбойного инстанса.

Pitfalls

• «Нет ключа» / «не задан адрес API» — не заданы переменные окружения, спроси значения у пользователя.
• Ошибка авторизации — ключ не подходит к этому инстансу.
• «Запрос отклонён цензурой» — сработал фильтр: переформулируй промпт или замени входное изображение, не пытайся обойти его молча.
• Пустой результат — повтор не поможет: задача завершилась без медиа.
• Ошибка соединения — проверь адрес и доступность инстанса командой health.