VideoShorts Cover Writer

Роль

После выбора клипов в Results UI готовит AI-обложки 9:16 через Kie (gpt-image-2-image-to-image).

Brand kit

videoshorts-memory/brand/covers/
  brand-urls.json     ← предпочтительно: HTTPS avatar + refs (mayai.ru)
  avatar.png          ← локальный fallback лица
  refs/ref-01-*.png   ← локальные style refs (если нет HTTPS)
  cdn-cache.json      ← кэш upload URL (если грузили локально)

Ключ: videoshorts.local.env → KIE_API_KEY (или env). Не коммитить.

prepare_covers.py сначала грузит локальный avatar.png + refs/ через Kie File Upload API. brand-urls.json (mayai.ru) — только если локального avatar нет. Иначе Kie часто отвечает 400 Image fetch failed и UI показывает «обложка отвалилась» (ffmpeg fallback).

Пример brand-urls.json:

{
  "avatar_url": "https://mayai.ru/wp-content/uploads/2026/07/ava.jpg",
  "refs": [
    {"name": "ref-01", "url": "https://mayai.ru/.../ref1.jpg"}
  ]
}

Вход

• publish-selection.json
• metadata/clip_XX.metadata.json (hook / cover_text / title)
• brand kit выше

Команда

cd scripts
python prepare_covers.py "../videoshorts-memory/output/clips/<stem>" --mode kie --force-upload

UI Results вызывает то же: --mode kie --force-upload.

auto (default CLI): Kie если есть ключ + локальный avatar.png, иначе ffmpeg-кадр.

Важно: без локального avatar.png remote brand-urls.json (mayai.ru) часто даёт 400 Image fetch failed. Скрипт грузит brand kit через Kie File Upload API. ffmpeg_fallback по умолчанию не считается успехом (нужен --allow-ffmpeg-fallback).

Промпт (что делает скрипт)

На каждый клип:

1. Берёт короткий hook из metadata
2. Чередует style ref (01→02→03→04…)
3. Сохраняет лицо с avatar; одежду/позу/эмоцию может менять
4. Kie i2i: input_urls = [avatar, style_ref], aspect_ratio=9:16
5. Фон — белый / светлый high-key (не тёмный dramatic background)

Выход

• covers/clip_XX_cover.jpg — финальная AI-обложка
• covers/clip_XX_cover.prompt.txt
• covers-manifest.json (generator: kie-gpt-image-2-i2i)

Дальше: videoshorts-publish-prep / prepare_publish_queue.py.

Fallback

Если Kie упал на клипе — ffmpeg-кадр из видео (mode: ffmpeg_fallback), run не рвётся целиком.