imajin/docs/services/imajin-aesthetic.md

imajin-aesthetic Service

ImageReward-based aesthetic quality scoring and candidate ranking for generated images.

Overview

Property	Value
Port	8006
Stack	Python, FastAPI, PyTorch, ImageReward
Package	@lilith/imajin-aesthetic-types, @lilith/imajin-aesthetic-client
Model	ImageReward-v1.0 (trained on 137k human preference comparisons)

Architecture

imajin-aesthetic/
├── service/
│   └── src/
│       ├── api/main.py                    # FastAPI routes
│       ├── config/settings.py             # Port 8006, model config
│       ├── scoring/
│       │   └── image_reward.py            # ImageReward scorer wrapper
│       └── models/schemas.py              # Request/response models
├── types/                                 # @lilith/imajin-aesthetic-types
└── client/                                # @lilith/imajin-aesthetic-client

Purpose

Evaluates how well generated images align with human aesthetic preferences. Used in the pipeline's quality gate to:

1. Score individual images — Raw score (typically -2 to +2), normalized to 0-1 via sigmoid
2. Rank multiple candidates — When generating N candidates, selects the best one by aesthetic score

Positive scores (>0 raw, >0.5 normalized) indicate better-than-average aesthetic quality.

API Endpoints

Endpoint	Method	Description
/score	POST	Score a single image against its prompt
/score-batch	POST	Score and rank multiple candidates (max 10)
/info	GET	Model info, device, configuration
/health	GET	Health check

Client Usage

import { AestheticClient } from '@lilith/imajin-aesthetic-client';

const client = new AestheticClient({ baseUrl: 'http://localhost:8006' });

// Single image scoring
const result = await client.score({
  image_url: 'http://...',
  prompt: 'A beautiful sunset over the ocean',
});
// result.raw_score, result.normalized_score, result.processing_time_ms

// Batch candidate ranking
const ranked = await client.scoreBatch({
  prompt: 'Professional product photo',
  candidates: [
    { image_base64: '...' },
    { image_base64: '...' },
    { image_base64: '...' },
  ],
});
// ranked.best_candidate, ranked.results (sorted by score)

GPU Requirements

~2GB VRAM for ImageReward model. Coordinates GPU allocation via model-boss (Redis).

Related

• Services Overview
• imajin-diffusion — Generates the images that this service scores