freepik-api/README.md

# Freepik API

REST API wrapping [Freepik's cloud AI API](https://docs.freepik.com/reference/ai-image-generator) for image generation, video generation, image editing, and media processing.

Containerized and deployed via Gitea CI/CD. Designed to be orchestrated alongside [facefusion-api](https://dev.pivoine.art/valknar/facefusion-api) — both share the same project patterns (FastAPI, Pydantic, router/schema/service structure).

## Quick Start

```bash
# Copy and configure environment
cp .env.example .env
# Edit .env and set FP_FREEPIK_API_KEY

# Build and run
docker compose up --build

# Verify
curl http://localhost:8001/api/v1/health
curl http://localhost:8001/api/v1/system
```

## API Endpoints

### Image Generation

| Endpoint | Model | Description |
|----------|-------|-------------|
| `POST /api/v1/generate/image/mystic` | Mystic | Freepik's ultra-realistic model |
| `POST /api/v1/generate/image/flux-dev` | Flux Dev | Black Forest Labs Flux Dev |
| `POST /api/v1/generate/image/flux-pro` | Flux Pro 1.1 | Black Forest Labs Flux Pro |
| `POST /api/v1/generate/image/seedream` | SeedReam 4 | ByteDance SeedReam |

All image generation endpoints accept `?sync=true` to block until the result is ready.

### Video Generation

| Endpoint | Model | Description |
|----------|-------|-------------|
| `POST /api/v1/generate/video/kling` | Kling O1 Pro | 1080p, 5/10s clips |
| `POST /api/v1/generate/video/minimax` | MiniMax Hailuo | 768p video |
| `POST /api/v1/generate/video/seedance` | Seedance 1.0 | ByteDance Seedance |

Video endpoints always return async task IDs (generation takes 1-5 min).

### Image Editing

| Endpoint | Description |
|----------|-------------|
| `POST /api/v1/edit/upscale/creative` | AI creative upscale with prompt guidance |
| `POST /api/v1/edit/upscale/precision` | Precision 2x/4x upscale |
| `POST /api/v1/edit/relight` | AI relighting |
| `POST /api/v1/edit/style-transfer` | Style transfer from reference image |
| `POST /api/v1/edit/expand` | Outpainting / image expansion |
| `POST /api/v1/edit/inpaint` | AI inpainting with mask and prompt |

### Utilities

| Endpoint | Description |
|----------|-------------|
| `POST /api/v1/util/remove-background` | Background removal (sync) |
| `POST /api/v1/util/classify` | AI-generated image classifier |
| `POST /api/v1/util/audio-isolate` | Audio track isolation |
| `POST /api/v1/generate/icon` | Text-to-icon generation |

### Task Management

| Endpoint | Description |
|----------|-------------|
| `GET /api/v1/tasks` | List tracked tasks |
| `GET /api/v1/tasks/{id}` | Get task status |
| `GET /api/v1/tasks/{id}/result` | Download task result |
| `DELETE /api/v1/tasks/{id}` | Delete task and cleanup files |

### System

| Endpoint | Description |
|----------|-------------|
| `GET /api/v1/health` | Health check |
| `GET /api/v1/system` | API key validity, active tasks, memory |

## Usage Examples

### Generate an image (async)

```bash
curl -X POST http://localhost:8001/api/v1/generate/image/flux-dev \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "a cat wearing a top hat, oil painting"}'

# Response: {"task_id": "abc-123", "status": "pending", ...}

# Poll until complete
curl http://localhost:8001/api/v1/tasks/abc-123

# Download result
curl http://localhost:8001/api/v1/tasks/abc-123/result -o result.png
```

### Generate an image (sync)

```bash
curl -X POST 'http://localhost:8001/api/v1/generate/image/mystic?sync=true' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "mountain landscape at sunset"}' \
  -o result.png
```

### Remove background

```bash
curl -X POST http://localhost:8001/api/v1/util/remove-background \
  -H 'Content-Type: application/json' \
  -d '{"image": "<base64-encoded-image>"}'
```

## Environment Variables

All prefixed with `FP_`:

| Variable | Default | Description |
|----------|---------|-------------|
| `FP_FREEPIK_API_KEY` | *(required)* | Freepik API key |
| `FP_FREEPIK_BASE_URL` | `https://api.freepik.com` | API base URL |
| `FP_OUTPUT_DIR` | `/data/outputs` | Result file storage |
| `FP_TEMP_DIR` | `/data/temp` | Temporary file storage |
| `FP_MAX_UPLOAD_SIZE_MB` | `50` | Max upload size |
| `FP_TASK_POLL_INTERVAL_SECONDS` | `5` | Polling interval for async tasks |
| `FP_TASK_POLL_TIMEOUT_SECONDS` | `600` | Max polling duration (10 min) |
| `FP_AUTO_CLEANUP_HOURS` | `24` | Auto-delete old results after N hours |
| `FP_WEBHOOK_SECRET` | *(empty)* | Optional webhook signature verification |

## Production Deployment

```bash
docker compose -f docker-compose.prod.yml up -d
```

The production compose pulls from the Gitea container registry (`dev.pivoine.art/valknar/freepik-api:latest`) and uses named volumes for persistent storage.

## Architecture

```
app/
  main.py              # FastAPI app, lifespan, httpx client lifecycle
  config.py            # Pydantic BaseSettings (FP_ env prefix)
  routers/             # API endpoint handlers
  schemas/             # Pydantic request/response models
  services/
    freepik_client.py  # httpx async client with retry on 429
    task_tracker.py    # In-memory task tracking with asyncio polling
    file_manager.py    # Download results, serve files, cleanup
    webhook.py         # Optional webhook receiver for task completion
```

This is a thin async HTTP client — all AI processing happens on Freepik's cloud infrastructure. No GPU or local model inference required.