# Reference Sheet Generator

Generate 3x3 reference grids from character photos for AI video generation workflows.

## Description

Upload a character photo and receive a 3x3 reference grid showing the character from 9 different angles. This helps maintain character consistency in AI video generation workflows.

## Authentication

**Required**: x402 payment

This endpoint requires payment via the x402 protocol. See the [Setup](./setup.md) for setup instructions.

## Request

**Endpoint**: `POST /api/reference-sheet/generate`

**Content-Type**: `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| image | file | Yes | Character photo (JPEG, PNG, WebP; max 10MB) |

## Response

**200 OK**

```json
{
  "success": true,
  "gridUrl": "/outputs/uuid-here-grid.png",
  "angleUrls": [
    "/outputs/uuid-here-angle-0.png",
    "/outputs/uuid-here-angle-1.png",
    "/outputs/uuid-here-angle-2.png",
    "/outputs/uuid-here-angle-3.png",
    "/outputs/uuid-here-angle-4.png",
    "/outputs/uuid-here-angle-5.png",
    "/outputs/uuid-here-angle-6.png",
    "/outputs/uuid-here-angle-7.png",
    "/outputs/uuid-here-angle-8.png"
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| success | boolean | Whether the generation succeeded |
| gridUrl | string | Path to the generated 3x3 grid image |
| angleUrls | string[] | Array of 9 paths to individual angle images |

## Error Codes

| Status | Code | Description |
|--------|------|-------------|
| 400 | VALIDATION_ERROR | Image is required and must be a valid image file under 10MB |
| 402 | PAYMENT_REQUIRED | x402 payment not completed |
| 422 | INVALID_REQUEST | Unable to process request |
| 500 | INTERNAL_ERROR | AI generation failed |
| 504 | AI_GENERATION_TIMEOUT | AI request timed out |

## Example

### Generate a reference sheet

```bash
npx x402-proxy -X POST \
  -F "image=@character-photo.png" \
  https://ps.codejar.net/api/reference-sheet/generate
```

**Response:**
```json
{
  "success": true,
  "gridUrl": "/outputs/550e8400-e29b-41d4-a716-446655440004-grid.png",
  "angleUrls": [
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-0.png",
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-1.png",
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-2.png",
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-3.png",
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-4.png",
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-5.png",
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-6.png",
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-7.png",
    "/outputs/550e8400-e29b-41d4-a716-446655440004-angle-8.png"
  ]
}
```

## Output Format

The generated reference sheet includes:

- **3x3 grid layout** (9 panels total)
- **Multiple angles**: Front, side, back, and various elevated/declined angles
- **Consistent character**: Same character rendered from different viewpoints
- **High resolution**: Suitable for AI video generation planning

## Use Cases

- **Character Consistency**: Maintain consistent character appearance across AI video frames
- **Video Generation**: Generate reference angles for character-focused AI video workflows
- **Pose Planning**: Visualize character from multiple angles for animation planning
- **3D Reference**: Create pseudo-3D reference sheets for character design