wiki/tasks/image-gen/reports/dev-2026-05-28-phase2-reference.md

Dev Report: Character Consistency — Phase 2 (Native Recraft Reference)

Дата: 2026-05-28 Статус: DONE

Задача

Найти рабочий формат передачи reference image в OpenRouter/Recraft API и реализовать нативную face consistency.

Сделано

• Task 1: Создан scripts/test_reference_api.py — тестирует 4 формата payload
• Task 1: Запущен с реальным reference — все 4 формата дают HTTP 200 + image
• Task 2: Добавлен --reference-strength в generate.py (default 0.3)
• Task 2: Модифицирован generate_openrouter() — multimodal content + strength
• Task 2: Интеграция с character_registry (--character + --reference-image работают)
• Task 2: E2E тест — генерация с reference + отправка в Telegram ✅
• Task 3: Обновлён references/recraft_api.md — секция img2img
• Task 3: Обновлён SKILL.md — Phase 2 документация, примеры, ограничения

Изменённые файлы

• skills/image-gen/scripts/generate.py — добавлен _encode_image_to_data_url(), расширен generate_openrouter() (reference_image, reference_strength), новый CLI флаг --reference-strength
• skills/image-gen/scripts/test_reference_api.py — новый тест-скрипт для API форматов
• skills/image-gen/references/recraft_api.md — секция img2img с tested formats
• skills/image-gen/SKILL.md — Phase 2 документация (v2.0)

Результат

API Discovery (test_reference_api.py)

Формат	HTTP	Image	Время
mixed_content (image+text in messages)	200	✅	14.4s
mixed_content + strength=0.3	200	✅	17.1s
mixed_content + strength=0.7	200	✅	18.6s
baseline (text only)	200	✅	7.8s

Выбранный формат

• Multimodal content array: [{type: "text", text: prompt}, {type: "image_url", image_url: {url: "data:image/jpeg;base64,..."}}]
• image_config.strength контролирует отклонение (0.3 = close to reference)

E2E тесты

1. --reference-image PATH --reference-strength 0.3 → ✅ генерация + TG delivery
2. --character NAME --reference-strength 0.3 → ✅ генерация + TG delivery

Проблемы и решения

• Нет проблем. Все форматы работают с первой попытки.
• img2img запросы ~2x медленнее (14-18s vs 8s text-only) — ожидаемо.

Архитектурные решения

• strength по умолчанию 0.3 (не 0.2 как в Recraft docs) — лучший баланс для face consistency
• Reference кодируется в base64 data URL inline — не требует внешнего хостинга
• A2E provider не поддерживает reference — gracefully ignored (reference_image param не передаётся)