# Storyboard Generator

Generate 3x3 storyboard grids from text prompts for AI video generation workflows.

## Description

Input a story description and receive a 3x3 storyboard grid with distinct scene panels. Each panel includes both visual content and burned-in scene description text, making it ideal for planning 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/storyboard-generator/generate`

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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| prompt | string | Yes | Story description (max 500 characters), e.g., "a warrior fights a dragon in a dark forest" |

## Response

**200 OK**

```json
{
  "imageUrl": "/outputs/uuid-here.png"
}
```

| Field | Type | Description |
|-------|------|-------------|
| imageUrl | string | Path to the generated storyboard image |

## Error Codes

| Status | Code | Description |
|--------|------|-------------|
| 400 | VALIDATION_ERROR | Prompt is required, must be non-empty, and under 500 characters |
| 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 storyboard

```bash
npx x402-proxy -X POST \
  -F "prompt=a warrior fights a dragon in a dark forest" \
  https://ps.codejar.net/api/storyboard-generator/generate
```

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

## Output Format

The generated storyboard is a single combined image containing:
- **3x3 grid layout** (9 panels total)
- **Scene progression**: Each panel shows a distinct scene advancing the story
- **Burned-in text**: Scene descriptions are visible directly on each panel
- **High resolution**: Suitable for AI video generation planning

## Use Cases

- **Video Planning**: Create storyboards to plan AI video generation sequences
- **Scene Breakdown**: Visualize story progression across 9 key moments
- **Prompt Engineering**: Test and refine story prompts before video generation
- **Creative Planning**: Storyboard scenes for animation, film, or game concepts