auto-sync: 2026-05-28 10:00:01

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

@@ -0,0 +1,49 @@
+# Dev Report: Character Consistency — Phase 2 (Native Recraft Reference)
+Дата: 2026-05-28
+Статус: DONE
+
+## Задача
+Найти рабочий формат передачи reference image в OpenRouter/Recraft API и реализовать нативную face consistency.
+
+## Сделано
+- [x] Task 1: Создан `scripts/test_reference_api.py` — тестирует 4 формата payload
+- [x] Task 1: Запущен с реальным reference — все 4 формата дают HTTP 200 + image
+- [x] Task 2: Добавлен `--reference-strength` в generate.py (default 0.3)
+- [x] Task 2: Модифицирован `generate_openrouter()` — multimodal content + strength
+- [x] Task 2: Интеграция с character_registry (--character + --reference-image работают)
+- [x] Task 2: E2E тест — генерация с reference + отправка в Telegram ✅
+- [x] Task 3: Обновлён `references/recraft_api.md` — секция img2img
+- [x] 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 не передаётся)