API Documentation

The Photova API provides powerful AI image editing capabilities through a simple REST interface. Background removal, upscaling, restoration, colorization, and more.

Installation

Self-host the Photova API on your own infrastructure. Requires PHP 8.2+ and PostgreSQL.

Requirements

• PHP 8.2 or higher
• Composer
• PostgreSQL 14+ (or Docker)
• At least one AI provider API key (Replicate, fal.ai, or remove.bg)

Quick Start with Docker

The fastest way to get started using Docker for PostgreSQL:

# Clone the repository
git clone https://github.com/phishy/photova.git
cd photova

# Start PostgreSQL via Docker
docker compose up postgres -d

# Setup Laravel
cd packages/photova-api
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate

# Start the server
php artisan serve

Environment Variables

Configure your .env file with the following:

Provider Configuration

Configure which provider handles each operation in config/photova.php:

'operations' => [
    'background-remove' => [
        'provider' => 'replicate',
        'fallback' => 'removebg',  // Optional fallback
    ],
    'upscale'  => ['provider' => 'replicate'],
    'unblur'   => ['provider' => 'replicate'],
    'colorize' => ['provider' => 'replicate'],
    'inpaint'  => ['provider' => 'replicate'],
    'restore'  => ['provider' => 'replicate'],
],

Storage Configuration

Configure asset storage buckets in config/photova.php. Each bucket can use a different storage backend.

Available Disks

Multiple Buckets Example

'storage' => [
    'default' => 'assets',
    'buckets' => [
        'assets' => [
            'disk' => 'local',   // Private, API-only access
            'path' => 'assets',
        ],
        'thumbnails' => [
            'disk' => 'public',  // Direct URL access
            'path' => 'thumbs',
        ],
        'cloud' => [
            'disk' => 's3',      // S3-compatible storage
            'path' => 'uploads',
        ],
    ],
],

S3 Environment Variables

To use the s3 disk, configure these in your .env:

# AWS S3
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=my-bucket

# For MinIO or other S3-compatible services
AWS_ENDPOINT=http://localhost:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

Using Buckets

Specify which bucket to use with the bucket query parameter:

# Upload to default bucket
curl -X POST /api/assets -F 'file=@image.png'

# Upload to specific bucket
curl -X POST /api/assets?bucket=cloud -F 'file=@image.png'

# List assets in bucket
curl /api/assets?bucket=cloud

Authentication

All API requests require authentication using an API key. You can create and manage your API keys from the Dashboard.

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer br_live_xxxxx

Alternatively, you can use the X-API-Key header:

X-API-Key: br_live_xxxxx

Base URL

All API requests should be made to:

https://api.photova.app

Errors

The API uses conventional HTTP response codes to indicate success or failure.

Error responses include a JSON body with details:

{
  "error": "Invalid API key",
  "requestId": "req_abc123"
}

Background Removal

Remove the background from an image, returning a transparent PNG.

Request Body

Example Request

curl -X POST https://api.photova.app/v1/background-remove \
  -H 'Authorization: Bearer br_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"image": "data:image/png;base64,..."}'

Response

{
  "image": "data:image/png;base64,...",
  "metadata": {
    "provider": "replicate",
    "processingTime": 1234,
    "requestId": "req_abc123"
  }
}

Upscale

Increase image resolution up to 4x using AI super-resolution.

Request Body

Example Request

curl -X POST https://api.photova.app/v1/upscale \
  -H 'Authorization: Bearer br_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"image": "data:image/png;base64,...", "options": {"scale": 4}}'

Restore

Restore old or damaged photos by fixing scratches, tears, and imperfections.

Request Body

Example Request

curl -X POST https://api.photova.app/v1/restore \
  -H 'Authorization: Bearer br_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"image": "data:image/png;base64,..."}'

Colorize

Add realistic color to black and white images using AI.

Request Body

Example Request

curl -X POST https://api.photova.app/v1/colorize \
  -H 'Authorization: Bearer br_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"image": "data:image/png;base64,..."}'

Deblur

Sharpen blurry images and restore clarity using AI deblurring.

Request Body

Example Request

curl -X POST https://api.photova.app/v1/unblur \
  -H 'Authorization: Bearer br_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"image": "data:image/png;base64,..."}'

Object Removal (Inpaint)

Remove unwanted objects from images by providing a mask.

Request Body

Example Request

curl -X POST https://api.photova.app/v1/inpaint \
  -H 'Authorization: Bearer br_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"image": "data:image/png;base64,...", "options": {"mask": "data:image/png;base64,..."}}'

Assets

Upload and manage images in your account storage.

curl -X POST https://api.photova.app/api/assets \
  -H 'Authorization: Bearer br_live_xxxxx' \
  -F 'file=@image.png'

Usage

Track your API usage and billing.

{
  "summary": {
    "totalRequests": 1234,
    "totalErrors": 12,
    "averageLatencyMs": 856,
    "byOperation": {
      "background-remove": { "requests": 500, "errors": 5 },
      "upscale": { "requests": 734, "errors": 7 }
    }
  }
}

{
  "current": {
    "used": 1234,
    "limit": 10000,
    "remaining": 8766
  }
}