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