# Avatar Generator API

Transform input images into stylized avatars using predefined artistic styles.

## Endpoint

```
POST /api/avatar-generator/generate
```

## Content-Type

`multipart/form-data`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image` | File | Yes | Input image file (JPEG, PNG, WebP). Max size: 10MB |
| `style` | String | Yes | Avatar style to apply (see available styles below) |

## Available Styles

| Style | Description |
|-------|-------------|
| `anime` | Japanese anime art style with vibrant colors, large expressive eyes, and clean line art |
| `3d-cartoon` | 3D cartoon style like Pixar/Disney movies with smooth shading and rounded shapes |
| `cartoon` | 2D Western cartoon style with bold outlines and flat colors |
| `pixel-art` | Retro pixel art style with limited color palette and visible pixels |
| `oil-painting` | Classical oil painting style with visible brushstrokes and rich textures |
| `watercolor` | Watercolor painting style with soft edges and translucent color washes |
| `sketch` | Pencil sketch style with graphite shading and paper texture |

## Success Response

**Status:** `200 OK`

```json
{
  "imageUrl": "/outputs/550e8400-e29b-41d4-a716-446655440000.png"
}
```

## Error Responses

### 400 Bad Request - Invalid Style

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid style. Must be one of: anime, 3d-cartoon, cartoon, pixel-art, oil-painting, watercolor, sketch",
    "details": null
  }
}
```

### 422 Unprocessable Entity - Missing Image

```json
{
  "error": {
    "code": "INVALID_IMAGE_DATA",
    "message": "No image provided",
    "details": null
  }
}
```

### 500 Internal Server Error - AI Generation Failed

```json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Avatar generation failed",
    "details": null
  }
}
```

## Examples

### Anime Style

```bash
curl -X POST http://localhost:3000/api/avatar-generator/generate \
  -F "image=@photo.jpg" \
  -F "style=anime"
```

### 3D Cartoon Style

```bash
curl -X POST http://localhost:3000/api/avatar-generator/generate \
  -F "image=@photo.jpg" \
  -F "style=3d-cartoon"
```

### Cartoon Style

```bash
curl -X POST http://localhost:3000/api/avatar-generator/generate \
  -F "image=@photo.jpg" \
  -F "style=cartoon"
```

### Pixel Art Style

```bash
curl -X POST http://localhost:3000/api/avatar-generator/generate \
  -F "image=@photo.jpg" \
  -F "style=pixel-art"
```

### Oil Painting Style

```bash
curl -X POST http://localhost:3000/api/avatar-generator/generate \
  -F "image=@photo.jpg" \
  -F "style=oil-painting"
```

### Watercolor Style

```bash
curl -X POST http://localhost:3000/api/avatar-generator/generate \
  -F "image=@photo.jpg" \
  -F "style=watercolor"
```

### Sketch Style

```bash
curl -X POST http://localhost:3000/api/avatar-generator/generate \
  -F "image=@photo.jpg" \
  -F "style=sketch"
```


## Use Cases

- **Social Media Profiles**: Create unique avatars for Twitter, Discord, Instagram, etc.
- **Gaming**: Generate character portraits for RPGs, MMOs, or indie games
- **Marketing**: Create branded mascots or character illustrations for campaigns
- **Personalization**: Customize user profiles in apps and platforms
- **Content Creation**: Generate thumbnails, blog headers, or video thumbnails
- **Gift & Merchandise**: Create personalized avatars for prints, mugs, or stickers