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

Скилл для генерации через Kandinsky API — REST-сервис с моделями Kandinsky (K6 — изображения, K5 — видео) и GigaAvatar.

• Base URL: задаётся через env KANDINSKY_API_BASE. Значение по умолчанию http://87.242.117.37:5051 — это приватный/operator-trusted инстанс, не публичный прод.
• Swagger: <KANDINSKY_API_BASE>/docs · спека: /openapi.json
• Авторизация: HTTP Bearer — заголовок Authorization: Bearer $KANDINSKY_API_KEY на каждом запросе к /tasks/.... Ключ берётся из env KANDINSKY_API_KEY (спроси у пользователя, если его нет).

⚠️ Безопасность ключа и транспорта#

Ключ — секрет, и Bearer-заголовок уходит на сервер открыто. Не отправляй KANDINSKY_API_KEY по обычному HTTP в недоверенной сети — его можно перехватить. Правила:

• Предпочитай HTTPS-эндпоинт. Если используешь KANDINSKY_API_BASE с https:// — всё ок.
• Plain http:// допустим только для loopback ( 127.0.0.1/ localhost) или доверенного приватного/VPN-инстанса, который контролирует владелец.
• Если KANDINSKY_API_BASE начинается с http:// и это не loopback/приватный адрес — предупреди пользователя о риске перехвата ключа и не продолжай без его явного согласия.
• Никогда не клади ключ в URL/query-параметры и не логируй его.

Префлайт (перед генерацией)#

Прежде чем создавать задачу (она тратит ресурсы провайдера), сделай дешёвую проверку:

1. Убедись, что KANDINSKY_API_KEY задан; если нет — запроси у пользователя.
2. Проверь KANDINSKY_API_BASE: что это валидный URL и что транспорт допустим по правилам безопасности выше (HTTPS либо loopback/доверенный приватный HTTP).
3. Проверь доступность сервиса дешёвым запросом: GET /health (без авторизации). При необходимости сверь схему: GET /openapi.json.
4. Только после этого отправляй POST /tasks/<тип>.

Это отсекает «дорогие» ошибки (неверный ключ/адрес, лежащий сервис) до запуска генерации.

Готовый клиент — scripts/kandinsky.py#

В скилл вшит Python-клиент (только stdlib, без зависимостей). Предпочитай его вместо ручных curl-запросов: он сам создаёт задачу, поллит статус и сохраняет файл.

Требует env KANDINSKY_API_KEY (и опц. KANDINSKY_API_BASE).

Как библиотека:

python

from kandinsky import KandinskyClient
c = KandinskyClient()
c.generate_image("закатные горы, кинематографично", resolution="1024x1024", out="pic.png")
c.edit_image("pic.png", "в стиле акварели", out="water.png")
c.upscale("pic.png", upscale=2, out="big.png")
c.text_to_video("волны на берегу", pro=True, out="clip.mp4")
c.animate_image("pic.png", "камера медленно облетает объект", quality="lite", out="anim.mp4")
c.avatar("face.png", "speech.wav", "говорящий аватар", out="avatar.mp4")

Как CLI:

bash

python scripts/kandinsky.py health                      # префлайт перед генерацией
python scripts/kandinsky.py t2i "закатные горы" --resolution 1024x1024 -o pic.png
python scripts/kandinsky.py i2i pic.png "в стиле акварели" -o water.png
python scripts/kandinsky.py superres pic.png --upscale 2 -o big.png
python scripts/kandinsky.py t2v "волны на берегу" --pro -o clip.mp4
python scripts/kandinsky.py i2v pic.png "камера облетает" --quality hd -o anim.mp4
python scripts/kandinsky.py avatar face.png speech.wav "аватар" -o avatar.mp4
python scripts/kandinsky.py status <task_id>
python scripts/kandinsky.py result <task_id> -o out.bin

Ниже — описание сырого API на случай отладки или вызова без клиента.

Общий принцип (асинхронно)#

Все генерации асинхронные. Паттерн всегда один:

text

1. POST /tasks/<тип>      → { "task_id": "..." }
2. GET  /tasks/{task_id}  → { "status": "..." }   # поллить раз в ~5–10 сек
3. когда готово:
   GET  /tasks/{task_id}/result                   # забрать результат

Тело POST-запроса всегда обёрнуто так:

json

{
  "censor": true,
  "params": { ... }
}

censor (по умолчанию true) — цензура текста промпта и входных картинок, плюс проверка результата перед выдачей. Оставляй true, если не просят иначе.

Эндпоинты и параметры (params)#

Изображения (Kandinsky K6)#

• POST /tasks/k6-image-t2i — текст → картинка. params: query (промпт), resolution ∈ 1024x1024 | 768x768 | 768x1280 | 1280x768 | auto, beautificator? ∈ enabled | disabled | gigachat-max (дефолт enabled).
• POST /tasks/k6-i2i — картинка(и) + текст → картинка. params: query, image (массив base64-строк), beautificator?.
• POST /tasks/k6_superres — апскейл. params: image (base64), upscale ∈ 2 | 4, one_step_t? (0..1 — сила следования оригиналу, напр. 0.3333). Только кратное ×2/×4, дробного нет.

Видео (Kandinsky K5)#

• POST /tasks/k5_video_t2v_lite — текст → видео (lite). params: query, resolution ∈ 512x512 | 512x768 | 768x512, beautificator?.
• POST /tasks/k5_video_t2v_pro — текст → видео (pro). params: query, resolution ∈ 768x1280 | 1280x768, beautificator?.
• POST /tasks/k5-i2v-lite — картинка → видео (lite). (этим оживляли ежа) params: query (промпт движения), image (base64), beautificator?.
• POST /tasks/k5-i2v-sd — картинка → видео (SD). params: те же.
• POST /tasks/k5-i2v-hd — картинка → видео (HD, дефолт beautificator gigachat-max). params: те же.

Аватар#

• POST /tasks/giga_avatar — фото + аудио → говорящий аватар. params: query, image (base64), audio (base64).

Статус и результат#

• GET /tasks/{task_id} → { "status": "..." }. Наблюдаемые значения: new (в очереди) → processing (выполняется) → done (готово); ошибка — fail.
• GET /tasks/{task_id}/result → результат (картинка/видео). Сохрани в файл.

Рабочий процесс «оживить картинку» (i2v)#

1. Получи исходную картинку: либо k6-image-t2i, либо уже готовый файл → переведи в base64.
2. POST /tasks/k5-i2v-lite (или -sd/ -hd под качество) с image и query-промптом движения. Видео короткое — уложи действие в один кадр смысла.
3. Полль GET /tasks/{task_id} до done, затем GET .../result, сохрани mp4.

Промпт движения делай про сам объект, а не только про камеру, иначе объект застынет, а двигаться будет лишь камера. Подробнее — references/prompting.md.

Грабли (учтённый опыт)#

• Апскейл (superres) может залипнуть в new — воркер не берёт задачу. Не полль бесконечно: после ~1–2 мин в new скажи пользователю и предложи альтернативу (сгенерить сразу в нужном разрешении / повторить позже).
• Видео модель не «видит» как поток. Чтобы оценить ролик — разложи на кадры: ffmpeg -i video.mp4 -vf fps=2 frame_%03d.png и посмотри кадры.
• Рейтлимит на статус — поллить не чаще раза в ~5–10 сек.
• Картинки/видео отдаются как base64/бинарь — сохраняй сразу в файл, не таскай длинный base64 по контексту.
• Censor включён по умолчанию: «острые» промпты или входные фото могут отклоняться. Если задача падает на цензуре — переформулируй промпт.

Минимальный пример (curl)#

bash

BASE="${KANDINSKY_API_BASE:-http://87.242.117.37:5051}"

# 0) префлайт: сервис жив? (дёшево, без авторизации)
curl -s "$BASE/health"
# → {"status":"ok"}  — только после этого тратим ресурсы на генерацию

# 1) создать t2i
curl -s -X POST "$BASE/tasks/k6-image-t2i" \
  -H "Authorization: Bearer $KANDINSKY_API_KEY" -H "Content-Type: application/json" \
  -d '{"censor":true,"params":{"query":"cinematic mountain landscape at sunrise","resolution":"1024x1024"}}'
# → {"task_id":"abc123"}

# 2) статус
curl -s "$BASE/tasks/abc123" -H "Authorization: Bearer $KANDINSKY_API_KEY"
# → {"status":"processing"}  (поллить до "done")

# 3) результат
curl -s "$BASE/tasks/abc123/result" -H "Authorization: Bearer $KANDINSKY_API_KEY" -o out.png

Полную схему всегда можно сверить в Swagger: http://87.242.117.37:5051/docs. Шпаргалка по эндпоинтам — references/api-cheatsheet.md, промптинг — references/prompting.md.