# CLAUDE.md

## Overview

Freepik API - A Python REST API wrapping the Freepik cloud AI API for image generation, video generation, image editing, and media processing. Containerized and deployed via Gitea CI/CD at `dev.pivoine.art`. Designed to be orchestrated alongside `facefusion-api`.

## Architecture

- **FastAPI** async web framework with httpx async client for Freepik API calls
- Thin async HTTP client wrapping remote Freepik cloud API (no local GPU needed)
- In-memory task tracker for polling async Freepik tasks
- Background polling with asyncio for active tasks

### Project Structure

```
app/
  main.py              # FastAPI app, lifespan, httpx client
  config.py            # Pydantic BaseSettings (FP_ env prefix)
  routers/             # API endpoint handlers
  schemas/             # Pydantic request/response models
  services/
    freepik_client.py  # httpx async client wrapper for Freepik API
    task_tracker.py    # Track submitted tasks, poll status, store results
    file_manager.py    # Download results, serve files, cleanup
    webhook.py         # Optional webhook receiver for task completion
```

## Common Commands

```bash
# Development
docker compose build
docker compose up

# Production
docker compose -f docker-compose.prod.yml up -d

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

## API Endpoints

- `POST /api/v1/generate/image/{model}` - Image generation (mystic, flux-dev, flux-pro, seedream)
- `POST /api/v1/generate/video/{model}` - Video generation (kling, minimax, seedance)
- `POST /api/v1/edit/upscale/{type}` - Image upscaling (creative, precision)
- `POST /api/v1/edit/relight` - AI relighting
- `POST /api/v1/edit/style-transfer` - Style transfer
- `POST /api/v1/edit/expand` - Image expansion
- `POST /api/v1/edit/inpaint` - AI inpainting
- `POST /api/v1/util/remove-background` - Background removal (sync)
- `POST /api/v1/util/classify` - AI image classifier
- `POST /api/v1/util/audio-isolate` - Audio isolation
- `POST /api/v1/generate/icon` - Text-to-icon
- `GET /api/v1/tasks/{id}` - Task status
- `GET /api/v1/tasks/{id}/result` - Download result
- `GET /api/v1/tasks` - List tasks
- `DELETE /api/v1/tasks/{id}` - Delete task
- `GET /api/v1/health` - Health check
- `GET /api/v1/system` - System info

## Environment Variables

All prefixed with `FP_`:
- `FP_FREEPIK_API_KEY` - Required Freepik API key
- `FP_FREEPIK_BASE_URL` - API base URL (default: https://api.freepik.com)
- `FP_OUTPUT_DIR` - Output storage path (default: /data/outputs)
- `FP_TEMP_DIR` - Temp storage path (default: /data/temp)
- `FP_MAX_UPLOAD_SIZE_MB` - Upload limit (default: 50)
- `FP_TASK_POLL_INTERVAL_SECONDS` - Poll interval (default: 5)
- `FP_TASK_POLL_TIMEOUT_SECONDS` - Poll timeout (default: 600)
- `FP_AUTO_CLEANUP_HOURS` - Auto cleanup interval (default: 24)
- `FP_WEBHOOK_SECRET` - Optional webhook verification secret

## Docker

- Single image, no GPU variant needed (cloud API)
- Port 8001 (avoids conflict with facefusion-api on 8000)
- Outputs persisted in `/data/outputs` volume

## Important Notes

- This is a thin client wrapping the Freepik cloud API - no local model inference
- Most endpoints return async task IDs; use `?sync=true` to block until completion
- Models are hosted by Freepik, not downloaded locally
- Git operations: always push with the valknarthing ssh key