Sebastian Krüger
99c24adfe8
FastAPI async wrapper for Freepik cloud AI API supporting image generation (Mystic, Flux Dev/Pro, SeedReam), video generation (Kling, MiniMax, Seedance), image editing (upscale, relight, style transfer, expand, inpaint), and utilities (background removal, classifier, audio isolation). Includes async task tracking with polling, Docker containerization, and Gitea CI/CD workflow. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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
|