mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
docs: add per-tool API documentation and fix parity gaps
- Create 53 per-tool VitePress documentation pages with accurate parameters from Zod schemas, example requests, and response formats - Add root llms.txt for LLM-friendly repo browsing - Fix OpenAPI spec: add auth and 422 error schemas to edit-metadata/inspect and strip-metadata/inspect sub-routes - Fix tool count inconsistency (52 -> 53) across landing site, e2e tests, and local docs - Rename color-adjustments.ts to adjust-colors.ts to match tool ID - Update VitePress sidebar with all 8 tool categories and top nav
This commit is contained in:
SnapOtter
@@ -0,0 +1,166 @@
|
||||
# Passport Photo
|
||||
|
||||
AI-powered passport and ID photo generator. Two-phase workflow: analyze (face detection + background removal) then generate (crop, resize, and tile for printing).
|
||||
|
||||
## API Endpoints
|
||||
|
||||
This tool uses a two-phase flow with separate endpoints for analysis and generation.
|
||||
|
||||
**Model bundle:** `background-removal` (4-5 GB)
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
`POST /api/v1/tools/passport-photo/analyze`
|
||||
|
||||
Detects face landmarks and removes the background. Returns landmark data and a preview for the frontend to display a crop preview.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| file | file | Yes | - | Image file (multipart) |
|
||||
| clientJobId | string | No | - | Optional job ID for progress tracking via SSE |
|
||||
|
||||
#### Example Request
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:13490/api/v1/tools/passport-photo/analyze \
|
||||
-F "file=@headshot.jpg"
|
||||
```
|
||||
|
||||
#### Response (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
||||
"filename": "headshot.jpg",
|
||||
"preview": "<base64-encoded PNG>",
|
||||
"previewWidth": 800,
|
||||
"previewHeight": 1067,
|
||||
"landmarks": {
|
||||
"leftEye": { "x": 0.42, "y": 0.35 },
|
||||
"rightEye": { "x": 0.58, "y": 0.35 },
|
||||
"eyeCenter": { "x": 0.50, "y": 0.35 },
|
||||
"chin": { "x": 0.50, "y": 0.65 },
|
||||
"forehead": { "x": 0.50, "y": 0.22 },
|
||||
"crown": { "x": 0.50, "y": 0.18 },
|
||||
"nose": { "x": 0.50, "y": 0.48 },
|
||||
"faceCenterX": 0.50
|
||||
},
|
||||
"imageWidth": 2400,
|
||||
"imageHeight": 3200
|
||||
}
|
||||
```
|
||||
|
||||
#### Progress (SSE, optional)
|
||||
|
||||
If `clientJobId` is provided, progress is streamed (0-30% for face detection, 30-95% for background removal).
|
||||
|
||||
#### Error: No Face Detected (422)
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "No face detected",
|
||||
"details": "Could not detect a face in the uploaded image. Please upload a clear, front-facing photo with good lighting."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Generate
|
||||
|
||||
`POST /api/v1/tools/passport-photo/generate`
|
||||
|
||||
Crops, resizes, and optionally tiles the photo onto a print sheet. Uses cached images from Phase 1 (no AI re-run).
|
||||
|
||||
#### Parameters (JSON body)
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| jobId | string | Yes | - | Job ID from Phase 1 |
|
||||
| filename | string | Yes | - | Original filename from Phase 1 |
|
||||
| countryCode | string | Yes | - | Country code for passport spec (e.g., `US`, `GB`, `IN`) |
|
||||
| documentType | string | No | `"passport"` | Document type (from country spec) |
|
||||
| bgColor | string | No | `"#FFFFFF"` | Background color hex |
|
||||
| printLayout | string | No | `"none"` | Print paper layout: `none`, `4x6`, `a4`, `letter` |
|
||||
| maxFileSizeKb | number | No | `0` | Max file size constraint in KB (0 = no limit) |
|
||||
| dpi | number | No | `300` | Output DPI (72-1200) |
|
||||
| customWidthMm | number | No | - | Custom photo width in mm (overrides country spec) |
|
||||
| customHeightMm | number | No | - | Custom photo height in mm (overrides country spec) |
|
||||
| zoom | number | No | `1` | Zoom factor (0.5-3). Values > 1 crop tighter |
|
||||
| adjustX | number | No | `0` | Horizontal position adjustment |
|
||||
| adjustY | number | No | `0` | Vertical position adjustment |
|
||||
| landmarks | object | Yes | - | Landmarks object from Phase 1 response |
|
||||
| imageWidth | number | Yes | - | Image width from Phase 1 response |
|
||||
| imageHeight | number | Yes | - | Image height from Phase 1 response |
|
||||
|
||||
#### Example Request
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:13490/api/v1/tools/passport-photo/generate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jobId": "a1b2c3d4-...",
|
||||
"filename": "headshot.jpg",
|
||||
"countryCode": "US",
|
||||
"documentType": "passport",
|
||||
"bgColor": "#FFFFFF",
|
||||
"printLayout": "4x6",
|
||||
"dpi": 300,
|
||||
"zoom": 1,
|
||||
"adjustX": 0,
|
||||
"adjustY": 0,
|
||||
"landmarks": { "leftEye": {"x":0.42,"y":0.35}, "rightEye": {"x":0.58,"y":0.35}, "eyeCenter": {"x":0.50,"y":0.35}, "chin": {"x":0.50,"y":0.65}, "forehead": {"x":0.50,"y":0.22}, "crown": {"x":0.50,"y":0.18}, "nose": {"x":0.50,"y":0.48}, "faceCenterX": 0.50 },
|
||||
"imageWidth": 2400,
|
||||
"imageHeight": 3200
|
||||
}'
|
||||
```
|
||||
|
||||
#### Response (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
||||
"downloadUrl": "/api/v1/download/{jobId}/headshot_passport.jpg",
|
||||
"dimensions": {
|
||||
"widthMm": 51,
|
||||
"heightMm": 51,
|
||||
"widthPx": 602,
|
||||
"heightPx": 602,
|
||||
"dpi": 300
|
||||
},
|
||||
"spec": {
|
||||
"country": "United States",
|
||||
"countryCode": "US",
|
||||
"documentType": "passport",
|
||||
"documentLabel": "Passport"
|
||||
},
|
||||
"printDownloadUrl": "/api/v1/download/{jobId}/headshot_passport_print_4x6.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Base Route
|
||||
|
||||
`POST /api/v1/tools/passport-photo`
|
||||
|
||||
Returns guidance to use the correct sub-endpoint.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Use /api/v1/tools/passport-photo/analyze or /generate"
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Requires the `background-removal` model bundle to be installed (4-5 GB).
|
||||
- Phase 1 runs AI (face landmarks + background removal) and caches results. Phase 2 is pure Sharp image manipulation (fast, no AI needed).
|
||||
- Landmarks are returned as normalized coordinates (0-1 range relative to image dimensions).
|
||||
- The `preview` field in the analyze response is a base64-encoded PNG (max 800px wide) for fast display.
|
||||
- Country specs include document dimensions, head height ratios, and eye-line positioning based on official passport photo requirements.
|
||||
- The `printLayout` option generates a tiled sheet on standard paper sizes (4x6", A4, Letter) with 2mm gutters between photos.
|
||||
- When `maxFileSizeKb` is set, the output is iteratively compressed to fit within the size limit.
|
||||
Reference in New Issue
Block a user