diff --git a/tasks/image-gen/reports/dev-2026-05-28-phase2-reference.md b/tasks/image-gen/reports/dev-2026-05-28-phase2-reference.md new file mode 100644 index 0000000..4744806 --- /dev/null +++ b/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 не передаётся)