--- name: kandinsky-skill description: >- Генерирует и редактирует медиа через Kandinsky: рисует изображения по описанию, перерисовывает и правит существующие картинки, повышает разрешение и качество, создаёт короткие видео по тексту или из фотографии, оживляет изображения и делает говорящие аватары из фото и аудио. Используй всякий раз, когда пользователь хочет создать или изменить визуальный контент — «нарисуй», «сгенерируй картинку», «сделай логотип, иллюстрацию, обои, постер, открытку, иконку, стикер, мем или аватарку», «перерисуй, поправь или отфотошопь фото», «дорисуй», «убери или замени фон», «замени лицо», «улучши качество, увеличь, апскейл», «сделай видео», «оживи картинку», «заставь фото говорить», «липсинк», «озвучь аватар» — даже если слово «Kandinsky» не прозвучало. Различай: «аватарка» как картинка профиля — это обычная генерация изображения (kandinsky_image), а «говорящий аватар» из фото и аудио — это kandinsky_avatar. Не для поиска готовых картинок в интернете, распознавания и описания фото, построения графиков по данным. version: 1.0.2 type: extension runtime: python3 entry: plugin.py permissions: [net, tool, route, widget] env_from_settings: [] when_to_use: >- Пользователь просит создать или изменить изображение либо видео (генерация, не поиск). Граница и пограничные случаи: если просят НАЙТИ готовое изображение в интернете, ОПИСАТЬ или распознать содержимое присланного фото, либо построить график по числам — это НЕ сюда. «Аватарка/аватар как картинка профиля» — обычная генерация изображения (kandinsky_image), а не kandinsky_avatar. Маршрут по глаголу: «отфотошопь, поправь, дорисуй, замени фон, замени лицо» существующее фото → kandinsky_edit_image; «улучши качество, увеличь, апскейл» → kandinsky_upscale; «оживи картинку, добавь движение» (без звука) → kandinsky_animate; «заставь фото говорить, липсинк, озвучь по аудио» (нужны фото и аудиофайл) → kandinsky_avatar. timeout_sec: 300 --- # Kandinsky API — картинки и видео Скилл генерации и редактирования медиа через **Kandinsky API**: изображения, короткие видео и говорящие аватары. Регистрирует инструменты агента и виджет настроек; сырой HTTP звать не нужно. ## Setup Чтобы начать: **включи скилл и заполни два поля** в разделе **«Настройки» → «Расширенные» → «Kandinsky API»**: - **Адрес Kandinsky API** — адрес инстанса, который тебе выдали (например `http://ваш-сервер:5051`). Значения по умолчанию нет: пока адрес не задан, навык никуда не ходит; - **API-ключ Kandinsky** — Bearer-ключ к этому инстансу. Больше ничего настраивать не нужно: фильтр контента включён, запросы идут на указанный адрес. Если у пользователя нет адреса и ключа — подскажи, что запросить доступ можно письмом на **kandinsky@kandinskylab.ai**. Ничего не подставляй от себя. ## Usage - `kandinsky_health` — префлайт: жив ли сервис и валидны ли настройки (дёшево, без генерации). Зови перед первой/дорогой генерацией или при непонятной ошибке. - `kandinsky_image(query, resolution?, beautificator?)` — текст → картинка. - `kandinsky_edit_image(image, query, …)` — картинка(и)+текст → отредактированная картинка. `image` — путь к файлу или base64. - `kandinsky_upscale(image, upscale=2|4, one_step_t?)` — увеличение качества ×2/×4. - `kandinsky_video(query, pro?, resolution?)` — текст → короткое видео. `pro=true` — качественнее и дольше. - `kandinsky_animate(image, query, quality=lite|sd|hd)` — оживить картинку (картинка → видео). - `kandinsky_avatar(image, audio, query?)` — фото+аудио → говорящий аватар. **Нужны и фото, и аудиофайл.** - `kandinsky_task_status(task_id)` / `kandinsky_task_result(task_id, ext?)` — для долгих задач и дозабора. `ext` можно не указывать: тип файла определяется по содержимому. > В инструментах с `image` (edit_image, upscale, animate, avatar) его можно **не указывать** — > тогда навык сам возьмёт **последний сгенерированный результат**. Так «оживи эту картинку», > «увеличь её», «поправь фон» работают без пути к файлу: путь тебе знать не нужно. > **Если адрес или ключ не заданы**, любой инструмент вернёт готовую подсказку с > точным путём: «Настройки» → «Расширенные» → «Kandinsky API» и названием поля. > **Передай её пользователю дословно** — он не знает, где эти поля. ## Result delivery (важно) **Результат навык показывает пользователю САМ — картинкой/видео прямо в чате.** Тебе (агенту) НЕ нужно ничего вставлять, и НЕ нужно знать путь к файлу. Как понять по ответу инструмента: - **`inline_delivered: true`** — картинка или видео **уже показаны пользователю в чате**. **Отвечать не нужно вообще**: ни подтверждающей фразы вроде «Картинка готова», ни пути, ни ссылки, ни base64, ни «FINAL ANSWER». Результат уже перед глазами — любой текст рядом с ним лишний шум. - **`inline_delivered: false`** — показать в чате не удалось (например, слишком большой файл). Тогда следуй полю `show_this`: одна строка о том, что файл сохранён, плюс путь из поля `file_path` в виде «Файл: …» — по нему файл видно во вкладке «Файлы». **Файл уже доставлен в чат навыком — не отправляй его повторно.** Не вызывай `send_photo` / `send_video` для результата генерации и не прикладывай файл ещё раз: в ленте появится второй экземпляр той же картинки. **Для чейнинга** путь передавать не нужно: чтобы применить операцию к последнему результату, просто зови инструмент без `image`. Коротко: результат уже виден пользователю — от тебя не нужно ничего. ## How it works Генерации асинхронные; инструменты сами создают задачу, поллят статус и забирают результат. Если задача долгая и инструмент упёрся в таймаут, он вернёт `task_id` — дозабери результат через `task_result(task_id)` позже. ## Security model - API-ключ хранится в приватных настройках навыка и в чат не попадает; в ответах инструментов его нет. - Входные файлы (`image`, `audio`) читаются **только** из рабочего каталога агента. Каталог секретов и состояния закрыт — кроме собственного каталога результатов навыка, он нужен для чейнинга. Проверка по реальному пути (`realpath`), при неизвестных границах — отказ. - Пишет навык только к себе: результаты в свой job-каталог, настройки в свой state-каталог. В репозиторий и системные пути — никогда. - Байты результата модели не возвращаются: только служебные поля ответа. - Если ключ уходит по незащищённому HTTP на публичный адрес, `kandinsky_health` возвращает поле `warning` — риск виден пользователю. ## Limits - `timeout_sec: 300` — потолок платформы; внутренние бюджеты 290 / 280 / 240 с держатся ниже него, чтобы инструмент успел вернуть `task_id`, а не был прибит. - Инлайн-показ: до 12 МБ для картинки и 40 МБ для видео. Крупнее — только путь к файлу. - Скачиваемый результат: не больше 200 МБ; служебные ответы (создание, статус, health) — не больше 8 МБ. - Каталог результатов автоматически не чистится. ## Pitfalls (учтённый опыт) - **Апскейл (superres) может залипнуть в `new`** — воркер не берёт задачу. Не жди бесконечно: инструмент вернёт `task_id`, предложи альтернативу (сгенерить сразу в нужном разрешении / повторить позже). - **Видео модель не «видит» как поток.** Чтобы оценить ролик — разложи на кадры: `ffmpeg -i video.mp4 -vf fps=2 frame_%03d.png`. - **Промпт движения для i2v** делай про сам объект, а не только про камеру, иначе объект застынет. Подробнее — `references/prompting.md`. - **«Заставить фото говорить» ≠ «оживить».** Говорящий аватар (`kandinsky_avatar`) требует и фото, **и аудиофайл** — если пользователь просит озвучку/липсинк, но аудио не приложил, сначала попроси аудио. Просто движение без звука — это `kandinsky_animate` (аудио не нужно). - **Censor** включён по умолчанию: «острые» промпты/фото могут отклоняться. Теперь инструмент возвращает понятную причину («Запрос отклонён цензурой: …») — просто переформулируй промпт, не жди таймаута. - **`beautificator`** — необязательный «улучшайзер» промпта (`enabled` / `disabled` / `gigachat-max`). Обычно не трогай: сервер сам ставит разумный дефолт. Укажи `disabled`, если нужен буквальный промпт без авто-приукрашивания. - **Ошибки понятные:** несуществующий путь → «Файл не найден»; неверное разрешение видео → список допустимых; застревание в очереди → быстрый понятный отказ, а не зависание. Шпаргалка по эндпоинтам — `references/api-cheatsheet.md`, промптинг — `references/prompting.md`.