Initial commit: Freepik REST API
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>
This commit is contained in:
155
README.md
Normal file
155
README.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user