freepik-api/README.md

Freepik API

REST API wrapping Freepik's cloud AI API for image generation, video generation, image editing, and media processing.

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

Quick Start

# 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)

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)

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

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

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.