89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
|
# 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
|