Skip to main content

​
Overview

Penquify includes a FastAPI REST server that exposes all generation capabilities over HTTP.

​
Starting the Server

pip install penquify[api]
uvicorn penquify.api.server:app --host 0.0.0.0 --port 8000
The server runs at http://localhost:8000 with auto-generated OpenAPI docs at /docs.

​
Configuration

Environment VariableDefaultDescription
GEMINI_API_KEY—Required for photo generation and verification
PENQUIFY_OUTPUToutputDirectory for generated files

​
Base URL

http://localhost:8000

​
Endpoints

MethodPathDescription
GET/Health check, returns name + version
GET/presetsList photo variation presets
GET/templatesList document templates
POST/generate/documentGenerate PDF + PNG from JSON
POST/generate/photosGenerate photos from an image
POST/generate/datasetFull pipeline: JSON -> PDF -> photos
POST/generate/from-uploadUpload PDF/image -> schema detection -> photos
POST/generate/configNatural language -> variation JSON
GET/documentsList all generated runs
GET/documents/{run_id}/{filename}Download a file from a run

​
Authentication

No authentication is required by default. Add your own middleware for production deployments.

​
Response Format

All endpoints return JSON. File generation endpoints return a run_id that can be used to retrieve files: 
{
  "run_id": "a1b2c3d4e5",
  "files": {
    "html": "output/a1b2c3d4e5/guia_despacho_00054321.html",
    "png": "output/a1b2c3d4e5/guia_despacho_00054321.png",
    "pdf": "output/a1b2c3d4e5/guia_despacho_00054321.pdf"
  }
}