50 lines
3.1 KiB
Markdown
50 lines
3.1 KiB
Markdown
# 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 не передаётся)
|