Files

Sebastian Krüger 99c24adfe8 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>

2026-02-16 14:07:36 +01:00

3.3 KiB

Raw Blame History

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

# 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

3.3 KiB Raw Blame History