Openinary

https://docs.openinary.dev
Admin
Openinary is an open-source, self-hostable alternative to Cloudinary that provides on-the-fly image...
Tokens:13,546
Snippets:128
Trust Score:4.6
Update:10 months ago
Show doc for...
Tokens:
Raw
### Setup Openinary Development Environment

Source: https://docs.openinary.dev/quickstart

Clones the Openinary repository, installs Node.js dependencies using pnpm, and starts the development servers. This is an alternative to using Docker for local development.

```bash
# Clone the repo
git clone https://github.com/openinary/openinary.git && cd openinary

# Install dependencies
pnpm install

# Start development servers
pnpm dev
```

--------------------------------

### Install Openinary Docker Image

Source: https://docs.openinary.dev/quickstart

Pulls the latest Openinary Docker image from Docker Hub. This is the first step before running the container.

```bash
docker pull openinary/openinary:latest
```

--------------------------------

### API Key Authentication Example

Source: https://docs.openinary.dev/security

Demonstrates how to use an API key for authentication when making requests to protected Openinary endpoints.

```APIDOC
## Using API Keys

**Authorization header:**

```bash
curl -H "Authorization: Bearer sk_your_key_here" \
  http://localhost:3000/t/image.jpg
```

**Protected Endpoints:**

* `GET /t/*` - Image and video transformation
* `POST /upload/*` - File upload
* `GET/POST /storage/*` - Storage operations
```

--------------------------------

### Install and Run Openinary in API Only Mode

Source: https://docs.openinary.dev/quickstart

Installs the Openinary API Docker image and runs it in a container, exposing only the API on port 3000. It uses Docker volumes for data persistence and an environment variable to set the mode. The API key is generated and shown in container logs.

```bash
docker pull openinary/openinary-api:latest

docker run -d -p 3000:3000 \
  -v openinary-cache:/app/apps/api/cache \
  -v openinary-public:/app/apps/api/public \
  -v openinary-db:/app/data \
  -e MODE=api \
  openinary/openinary-api:latest
```

--------------------------------

### Run Openinary with S3 Compatible Storage

Source: https://docs.openinary.dev/quickstart

Starts Openinary in a Docker container, configured to use S3-compatible cloud storage. Environment variables are used to specify storage credentials and endpoint. It also uses a Docker volume for database persistence.

```bash
docker run -d -p 3000:3000 \
  -v openinary-db:/app/data \
  -e STORAGE_REGION=us-east-1 \
  -e STORAGE_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXXX \
  -e STORAGE_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e STORAGE_BUCKET_NAME=openinary-filebase \
  -e STORAGE_ENDPOINT=https://s3.filebase.com/ \
  openinary/openinary:latest
```

--------------------------------

### Run Openinary in Normal Mode (Dashboard + API)

Source: https://docs.openinary.dev/quickstart

Starts Openinary in a Docker container, exposing the dashboard and API on port 3000. It uses Docker volumes for data persistence (cache, public files, and database).

```bash
docker run -d -p 3000:3000 \
  -v openinary-cache:/app/apps/api/cache \
  -v openinary-public:/app/apps/api/public \
  -v openinary-db:/app/data \
  openinary/openinary:latest
```

--------------------------------

### HTTP Example: Optimize Video

Source: https://docs.openinary.dev/media-transformations/overview

Illustrates how to optimize a video file by setting its width to 1280 pixels, height to 720 pixels, and quality to 80. This example shows video compression and quality control.

```http
GET /t/w_1280,h_720,q_80/video.mp4
```

--------------------------------

### HTTP Example: Resize Image

Source: https://docs.openinary.dev/media-transformations/overview

Demonstrates how to resize an image to specific dimensions (800 pixels wide and 600 pixels high) using the transformation endpoint. This is a basic example of applying a single transformation.

```http
GET /t/w_800,h_600/image.jpg
```

--------------------------------

### HTTP Example: Multiple Image Transformations

Source: https://docs.openinary.dev/media-transformations/overview

Shows how to combine multiple transformation parameters in a single request for an image. This example resizes the image to 400x400 pixels, fills the area, focuses on the face, and sets quality to 85.

```http
GET /t/w_400,h_400,c_fill,g_face,q_85/portrait.jpg
```

--------------------------------

### Generate Mobile-Friendly Video (HTTP)

Source: https://docs.openinary.dev/media-transformations/video-transformations

This example shows how to generate low-bandwidth video versions suitable for mobile users on slower connections. It involves an HTTP GET request with specific width, height, and quality parameters.

```http
GET /t/w_640,h_360,q_65/video.mp4
```

--------------------------------

### Curl Command for Creating an API Key

Source: https://docs.openinary.dev/security

Example of using curl to create a new API key via the `/api-keys/create` endpoint. It includes the necessary Authorization header and a JSON payload specifying the key's name and expiration. This is part of the API key management process.

```bash
curl -X POST http://localhost:3000/api-keys/create \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Key", "expiresIn": 31536000}'
```

--------------------------------

### HTTP GET Request for Image Resizing with Aspect Ratio

Source: https://docs.openinary.dev/media-transformations/image-transformations

This example illustrates an HTTP GET request for resizing an image while maintaining a specific aspect ratio. It uses 'ar_16:9' to enforce a widescreen format and 'w_1920,h_1080' for precise dimensions, with automatic cropping applied.

```http
GET /t/ar_16:9,w_1920,h_1080/banner.jpg
```

--------------------------------

### Generate High-Quality Presentation Video (HTTP)

Source: https://docs.openinary.dev/media-transformations/video-transformations

This example illustrates how to maintain maximum quality for professional presentations and demos by generating high-resolution MP4 videos. It uses an HTTP GET request with parameters for full HD resolution and high quality.

```http
GET /t/w_1920,h_1080,q_95/presentation.mp4
```

--------------------------------

### API Key Management (API-only Mode)

Source: https://docs.openinary.dev/changelog

Details on how to use Openinary in API-only mode, including information on auto-generated API keys for headless setups.

```APIDOC
## API-only Mode

### Description
Openinary can be deployed as a standalone API service. In this mode, API keys are auto-generated, providing a headless setup for media processing.

### Accessing API Keys
API keys are automatically generated upon deployment in API-only mode. Consult your deployment environment's documentation or logs to retrieve the generated API key.

### Authentication
All requests to the API-only endpoint must include the generated API key in the `Authorization` header.

**Example Header:**
`Authorization: Bearer YOUR_AUTO_GENERATED_API_KEY`
```

--------------------------------

### Generate Social Media Optimized Video (HTTP)

Source: https://docs.openinary.dev/media-transformations/video-transformations

This example demonstrates how to create square videos optimized for social media feeds like Instagram and X. It utilizes HTTP GET requests with transformation parameters.

```http
GET /t/w_1080,h_1080,q_85/social.mp4
```

--------------------------------

### API Standalone Mode Initialization

Source: https://docs.openinary.dev/security

Explains the process of API key generation and usage in API Standalone Mode, emphasizing the importance of saving the generated key.

```APIDOC
## API Standalone Mode

**Mode:** `MODE=api`

On first startup, the system generates an API key and displays it in the console.

<Warning>
  **Save this key!** It's shown only once and cannot be retrieved later.
</Warning>

No email/password is created or displayed in this mode.
```

--------------------------------

### Trim Video Segment and Resize

Source: https://docs.openinary.dev/media-transformations/video-transformations

This example demonstrates how to trim a specific segment of a video and resize it simultaneously. It uses `so` and `eo` for trimming and `w`, `h` for resizing, resulting in a shorter video clip.

```http
GET /t/w_400,h_300,so_5,eo_12/video.mp4
```

--------------------------------

### HTTP GET Request for Image Format Conversion and Optimization

Source: https://docs.openinary.dev/media-transformations/image-transformations

This code demonstrates an HTTP GET request to resize an image and convert it to the AVIF format for better compression. It includes 'f_avif' for format specification and 'q_80' to set an optimized quality level, along with desired dimensions.

```http
GET /t/w_1200,h_800,f_avif,q_80/photo.jpg
```

--------------------------------

### Docker Security Practices

Source: https://docs.openinary.dev/security

Outlines security configurations for running Openinary in Docker, including running as a non-root user and managing volume permissions.

```APIDOC
## Docker Security

### Non-Root User

All containers run as user `node`:

* Prevents privilege escalation
* Limits damage if compromised
* Automatic ownership: `chown -R node:node /app`

### Volume Permissions

```yaml
# docker-compose.yml
volumes:
  - ./data:/app/data          # Database
  - ./backups:/backup         # Backups
```

### Startup Security

**`scripts/secure-db.sh` runs automatically:**

* Creates `/data` directory
* Sets database permissions to 600
* Verifies security
* Displays status
```

--------------------------------

### Review API Key Audit Logs (Bash)

Source: https://docs.openinary.dev/security

This snippet shows how to review audit logs for API key activity using Docker. It filters the Docker logs of the 'openinary_api' container for lines containing 'api_key.success'. Ensure Docker is installed and the 'openinary_api' container is running.

```bash
docker logs openinary_api | grep "api_key.success"
```

--------------------------------

### Restore Database from Backup (Bash)

Source: https://docs.openinary.dev/security

This sequence of commands restores the database from a compressed backup file and restarts the associated services. It uses Docker to execute a restore script and then restarts the Docker Compose services. Ensure the backup path and script name are correct and that Docker Compose is configured.

```bash
docker exec openinary_api /app/scripts/restore-db.sh /backup/latest.db.gz
docker compose restart
```

--------------------------------

### GET /t/[transformations]/path/to/file.ext

Source: https://docs.openinary.dev/media-transformations/overview

This endpoint allows for dynamic media transformations. Transformations are specified as comma-separated parameters in the URL, which are applied sequentially to the requested file. Supports both image and video transformations.

```APIDOC
## GET /t/[transformations]/path/to/file.ext

### Description
Applies a series of transformations to an image or video file specified by its path. Transformations are processed on-demand and can be combined.

### Method
GET

### Endpoint
`/t/[transformations]/path/to/file.ext`

### Parameters
#### Path Parameters
- **transformations** (string) - Required - A comma-separated list of transformation parameters (e.g., `w_800,h_600,q_80`).
- **path/to/file.ext** (string) - Required - The path to the media file to be transformed.

### Request Example
```http
GET /t/w_800,h_600/image.jpg
```

### Response
#### Success Response (200)
- The transformed media file (image or video).

#### Response Example
(Returns the binary data of the transformed media file)
```

--------------------------------

### HTTP GET Request for Smart Image Cropping with Face Detection

Source: https://docs.openinary.dev/media-transformations/image-transformations

This snippet shows an HTTP GET request for creating a square thumbnail using smart cropping. It specifies dimensions, the 'fill' crop mode, and 'g_face' for AI-powered face detection to ensure the primary subject is optimally framed.

```http
GET /t/w_400,h_400,c_fill,g_face/portrait.jpg
```

--------------------------------

### Security Best Practices for API Keys and Passwords

Source: https://docs.openinary.dev/security

Provides essential best practices for handling API keys and passwords securely to prevent common vulnerabilities.

```APIDOC
## Security Best Practices

### API Keys

<Check>
  **Do:**

  * Store in environment variables
  * Use different keys per service
  * Set appropriate expiration
  * Rotate regularly
  * Disable unused keys
</Check>

<Warning>
  **Don't:**

  * Commit to version control
  * Share between environments
  * Use same key everywhere
  * Keep expired keys enabled
</Warning>

### Passwords

**Requirements:**

* Minimum 8 characters (12+ in production)
* Mixed case, numbers, symbols

### Rate Limiting

* Built-in: 100 requests/minute per API key
* Configurable in `packages/shared/src/auth.ts`
```

--------------------------------

### Docker Compose Volume Configuration for Security

Source: https://docs.openinary.dev/security

Illustrates the volume configuration in a `docker-compose.yml` file. It shows how to map local directories for data persistence and backups, highlighting the importance of secure volume management in containerized environments. These volumes are crucial for data integrity and recovery.

```yaml
#docker-compose.yml
volumes:
  - ./data:/app/data          # Database
  - ./backups:/backup         # Backups
```

--------------------------------

### Extract Thumbnail Frame

Source: https://docs.openinary.dev/media-transformations/video-transformations

This example shows how to extract a single frame from a video at a specified time as a thumbnail image. It uses the `so` parameter for the time and `f` to specify the thumbnail format (e.g., WebP).

```http
GET /t/w_400,h_300,so_5,f_webp/video.mp4
```

--------------------------------

### Configure Cloudflare R2 Storage for Openinary

Source: https://docs.openinary.dev/configuration

Configures Openinary to use Cloudflare R2 for storage. This setup requires specific endpoint details along with access keys and bucket information.

```bash
STORAGE_REGION=auto
STORAGE_ACCESS_KEY_ID=your_r2_access_key
STORAGE_SECRET_ACCESS_KEY=your_r2_secret_key
STORAGE_BUCKET_NAME=your-bucket-name
STORAGE_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
STORAGE_PUBLIC_URL=https://your-custom-domain.com
```

--------------------------------

### API Key Management Endpoints

Source: https://docs.openinary.dev/security

Provides details on the API endpoints available for managing API keys, including creation, listing, updating, and deletion.

```APIDOC
## API Key Endpoints

| Method | Endpoint           | Description          |
| ------ | ------------------ | -------------------- |
| POST   | `/api-keys/create` | Create new API key   |
| GET    | `/api-keys/list`   | List user's API keys |
| PATCH  | `/api-keys/:keyId` | Update API key       |
| DELETE | `/api-keys/:keyId` | Delete API key       |

**Example - Create key:**

```bash
curl -X POST http://localhost:3000/api-keys/create \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Key", "expiresIn": 31536000}'
```
```

--------------------------------

### Database Security Configuration

Source: https://docs.openinary.dev/security

Details the security measures for the SQLite database, including its location, file permissions, and the purpose of different tables.

```APIDOC
## Auth Database Security

### SQLite Configuration

**Location:** `/data/auth.db` (configurable via `DB_PATH`)

**File Permissions:**

* Automatically set to `600` (owner read/write only)
* Enforced by `scripts/secure-db.sh` on startup
* Validated by health check endpoint

**Tables:**

* `user` - User accounts (passwords bcrypt-hashed)
* `session` - Web sessions
* `account` - Auth providers
* `verification` - Email/phone verification
* `apiKey` - API keys (hashed)
```

--------------------------------

### Curl Command for API Key Authentication

Source: https://docs.openinary.dev/security

Demonstrates how to authenticate API requests using a Bearer token with an API key. This is essential for accessing protected endpoints programmatically. The `Authorization` header should contain the API key prefixed with 'Bearer '.

```bash
curl -H "Authorization: Bearer sk_your_key_here" \
  http://localhost:3000/t/image.jpg
```

--------------------------------

### HTTP GET Endpoint Structure for Media Transformations

Source: https://docs.openinary.dev/media-transformations/overview

Defines the general URL structure for applying transformations to media files. Transformations are specified as comma-separated parameters before the file path. The system applies these transformations sequentially.

```http
GET /t/[transformations]/path/to/file.ext
```

--------------------------------

### Check Database Integrity (Bash)

Source: https://docs.openinary.dev/security

This command checks the integrity of the SQLite database used for authentication. It executes the 'PRAGMA integrity_check;' command within the 'auth.db' file inside the 'openinary_api' container. Requires Docker and access to the 'openinary_api' container.

```bash
docker exec openinary_api sqlite3 /app/data/auth.db "PRAGMA integrity_check;"
```

--------------------------------

### Copy Environment Template for Openinary

Source: https://docs.openinary.dev/configuration

Copies the Openinary environment template file to be configured for use. This is a preparatory step before configuring cloud storage settings.

```bash
cp apps/api/env.template apps/api/.env
```

--------------------------------

### Generate Low-Resolution Preview

Source: https://docs.openinary.dev/media-transformations/video-transformations

This snippet shows how to create a low-resolution preview of a video for faster loading. It uses the `w` and `h` parameters to set smaller dimensions and `q` for lower quality compression.

```http
GET /t/w_640,h_360,q_60/preview.mp4
```

--------------------------------

### Responsive Thumbnail with Padding (HTTP)

Source: https://docs.openinary.dev/media-transformations/image-transformations

Creates a responsive thumbnail with padding and a specified background color. This ensures consistent dimensions for thumbnails.

```http
GET /t/w_400,h_300,c_pad,b_rgb:f5f5f5,q_80/thumbnail.jpg
```

--------------------------------

### Responsive thumbnail with padding

Source: https://docs.openinary.dev/media-transformations/image-transformations

Creates a responsive thumbnail image with a specified padding and background color, ideal for consistent display.

```APIDOC
## GET /t/w_400,h_300,c_pad,b_rgb:f5f5f5,q_80/thumbnail.jpg

### Description
Generates a thumbnail image with a width of 400 pixels and a height of 300 pixels. It uses `c_pad` to add padding to maintain aspect ratio and `b_rgb:f5f5f5` to set a light gray background. The quality is set to 80 (`q_80`).

### Method
GET

### Endpoint
/t/w_400,h_300,c_pad,b_rgb:f5f5f5,q_80/thumbnail.jpg

### Parameters
#### Path Parameters
- **w_400** (integer) - Width of the image in pixels, set to 400.
- **h_300** (integer) - Height of the image in pixels, set to 300.
- **c_pad** (string) - Crop mode set to 'pad' to add padding and maintain aspect ratio.
- **b_rgb:f5f5f5** (string) - Background color in RGB format, set to light gray (f5f5f5).
- **q_80** (integer) - Quality setting, ranging from 0 to 100, with 80 providing good quality.

### Request Example
```http
GET /t/w_400,h_300,c_pad,b_rgb:f5f5f5,q_80/thumbnail.jpg
```

### Response
#### Success Response (200)
- **image_data** (binary) - The padded thumbnail image data.
```

--------------------------------

### Configure Generic S3-Compatible Storage for Openinary

Source: https://docs.openinary.dev/configuration

Enables Openinary to connect with various S3-compatible storage providers like Minio, DigitalOcean Spaces, or Wasabi. Requires specifying the endpoint URL.

```bash
STORAGE_REGION=us-east-1
STORAGE_ACCESS_KEY_ID=your_access_key
STORAGE_SECRET_ACCESS_KEY=your_secret_key
STORAGE_BUCKET_NAME=your-bucket-name
STORAGE_ENDPOINT=https://your-s3-compatible-endpoint.com
STORAGE_PUBLIC_URL=https://your-cdn-domain.com
```

--------------------------------

### Configure AWS S3 Storage for Openinary

Source: https://docs.openinary.dev/configuration

Sets up Openinary to use AWS S3 for storage. Requires region, access keys, bucket name, and public URL configuration.

```bash
STORAGE_REGION=us-east-1
STORAGE_ACCESS_KEY_ID=your_aws_access_key
STORAGE_SECRET_ACCESS_KEY=your_aws_secret_key
STORAGE_BUCKET_NAME=your-bucket-name
STORAGE_PUBLIC_URL=https://your-bucket-name.s3.us-east-1.amazonaws.com
```

--------------------------------

### WebP Fallback Encoding Logic for Browsers

Source: https://docs.openinary.dev/media-transformations/intelligent-compression

This logic describes the fallback mechanism to WebP for browsers that support it but not AVIF. The process includes content analysis, WebP encoding, size comparison, and delivering the WebP file, offering a balance of compression and compatibility.

```text
Content Analysis → WebP encoding → Size comparison → Deliver WebP
```

--------------------------------

### Media Transformations API

Source: https://docs.openinary.dev/changelog

This section details the API endpoints for performing on-the-fly media transformations, including image and video processing, as well as advanced features like video trimming and thumbnail generation.

```APIDOC
## POST /transformations

### Description
This endpoint allows for on-the-fly media transformations such as resizing, cropping, optimization, and video processing.

### Method
POST

### Endpoint
/transformations

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the media to transform.
- **actions** (array) - Required - An array of transformation actions to apply.

#### Request Body
```json
{
  "url": "string",
  "actions": [
    {
      "type": "string",
      "params": {}
    }
  ]
}
```

### Request Example
```json
{
  "url": "https://example.com/image.jpg",
  "actions": [
    {
      "type": "resize",
      "params": {
        "width": 500,
        "height": 300
      }
    },
    {
      "type": "format",
      "params": {
        "format": "webp"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **transformed_url** (string) - The URL of the transformed media.

#### Response Example
```json
{
  "transformed_url": "https://cdn.openinary.dev/transformed/image.webp"
}
```

## POST /transformations/video/trim

### Description
Trims a video using specified start and end offsets.

### Method
POST

### Endpoint
/transformations/video/trim

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the video to trim.
- **so** (integer) - Required - Start offset in seconds.
- **eo** (integer) - Required - End offset in seconds.

### Request Example
```json
{
  "url": "https://example.com/video.mp4",
  "so": 10,
  "eo": 30
}
```

### Response
#### Success Response (200)
- **transformed_url** (string) - The URL of the trimmed video.

#### Response Example
```json
{
  "transformed_url": "https://cdn.openinary.dev/transformed/video_trimmed.mp4"
}
```

## POST /transformations/video/thumbnail

### Description
Extracts a thumbnail from a video at a specified time offset.

### Method
POST

### Endpoint
/transformations/video/thumbnail

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the video.
- **so** (integer) - Required - Time offset in seconds to extract the frame.
- **format** (string) - Optional - Desired image format (webp, jpeg, png). Defaults to webp.

### Request Example
```json
{
  "url": "https://example.com/video.mp4",
  "so": 15,
  "format": "png"
}
```

### Response
#### Success Response (200)
- **thumbnail_url** (string) - The URL of the generated thumbnail.

#### Response Example
```json
{
  "thumbnail_url": "https://cdn.openinary.dev/transformed/video_thumbnail.png"
}
```
```

--------------------------------

### HTTP Request for Forced AVIF Format

Source: https://docs.openinary.dev/media-transformations/intelligent-compression

This HTTP request demonstrates how to manually force AVIF format for an image, bypassing the automatic selection process. It's useful when specific AVIF requirements override the default intelligent optimization.

```http
GET /t/f_avif,q_80/image.jpg
```

--------------------------------

### Modern Browser AVIF Encoding Logic

Source: https://docs.openinary.dev/media-transformations/intelligent-compression

This logic outlines the process for delivering AVIF format to modern browsers. It involves content analysis, AVIF encoding, size comparison, and finally delivering the AVIF file, prioritizing it for its superior compression.

```text
Content Analysis → AVIF encoding → Size comparison → Deliver AVIF
```

--------------------------------

### Legacy Browser JPEG/PNG Encoding Logic

Source: https://docs.openinary.dev/media-transformations/intelligent-compression

This logic details the strategy for serving older browsers that do not support modern formats like AVIF or WebP. It focuses on encoding content as JPEG or PNG to ensure maximum compatibility across all devices and browsers.

```text
Content Analysis → JPEG/PNG encoding → Deliver legacy format
```

--------------------------------

### Video Transformations API

Source: https://docs.openinary.dev/media-transformations/video-transformations

This API endpoint allows for comprehensive video transformations including resizing, compression, trimming, and thumbnail extraction. You can specify various parameters to control the output.

```APIDOC
## GET /t/{transformations}/[video_path]

### Description
Applies a series of transformations to a video, such as resizing, compression, trimming, and format conversion. Transformations are specified as a comma-separated list of parameters in the path.

### Method
GET

### Endpoint
`/t/{transformations}/[video_path]`

### Parameters
#### Path Parameters
- **transformations** (string) - Required - Comma-separated list of transformation parameters.
- **video_path** (string) - Required - The path to the video file.

#### Query Parameters
None

#### Request Body
None

### Request Example
```http
GET /t/w_1280,h_720,q_80/video.mp4
```

### Response
#### Success Response (200)
- **video** (binary) - The transformed video or image file.

#### Response Example
(Binary video/image data)

### Transformations Parameters Reference:

| Parameter | Full Name    | Description                                                 |
| --------- | ------------ | ----------------------------------------------------------- |
| `w`       | width        | Video width in pixels                                       |
| `h`       | height       | Video height in pixels                                      |
| `c`       | crop         | Crop mode for resizing (`fill`, `crop`)                     |
| `q`       | quality      | Compression quality using CRF (1-100), default `75`         |
| `so`      | start offset | Start time in seconds for trimming or thumbnail extraction  |
| `eo`      | end offset   | End time in seconds for trimming (exclusive)                |
| `f`       | format       | Output format (`mp4`, `webp`, `jpeg`, `png`)              |

**Example Transformations:**
- **HD Optimization**: `w_1280,h_720,q_80`
- **Preview Generation**: `w_640,h_360,q_60`
- **Video Trimming**: `w_400,h_300,so_5,eo_12`
- **Thumbnail Extraction**: `w_400,h_300,so_5,f_webp`
```

--------------------------------

### Automatic Image Optimization

Source: https://docs.openinary.dev/media-transformations/intelligent-compression

The system automatically selects the optimal image format based on browser capabilities and content analysis. It prioritizes AVIF, then WebP, followed by JPEG and PNG.

```APIDOC
## Automatic Image Optimization

### Description
This endpoint leverages an intelligent compression system to automatically select the best image format (AVIF, WebP, JPEG, PNG) based on browser support and content analysis, ensuring optimal performance and quality.

### Method
GET

### Endpoint
`/t/{format_directives}/image.[jpg|png|...]`

### Query Parameters
- **Accept** (string) - Optional - The `Accept` header from the client, used to detect supported formats.
- **User-Agent** (string) - Optional - The `User-Agent` header from the client, used to detect supported formats.

### Request Example
```http
GET /image.jpg
Accept: image/avif,image/webp
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36
```

### Response
#### Success Response (200)
- **image** (binary) - The optimized image in the best-selected format.

#### Response Example
(Binary image data, typically served with `Content-Type` header indicating the format, e.g., `image/avif`)
```

--------------------------------

### HTTP Request for Forced JPEG Format

Source: https://docs.openinary.dev/media-transformations/intelligent-compression

This HTTP request illustrates how to force JPEG format for an image, ensuring maximum compatibility. It bypasses intelligent selection and is recommended only for specific client requirements that necessitate JPEG output.

```http
GET /t/f_jpeg,q_90/image.jpg
```

--------------------------------

### Manual Image Format Override

Source: https://docs.openinary.dev/media-transformations/intelligent-compression

Allows for manual specification of the output image format and quality, bypassing the automatic optimization logic.

```APIDOC
## Manual Image Format Override

### Description
Manually force a specific image format (AVIF, WebP, JPEG) and quality level, overriding the automatic format selection. Use this only when specific requirements necessitate it.

### Method
GET

### Endpoint
`/t/f_[format],q_[quality]/image.[jpg|png|...]`

### Path Parameters
- **format** (string) - Required - The desired output format. Supported values: `avif`, `webp`, `jpeg`.
- **quality** (integer) - Required - The desired quality level (0-100).

### Request Example
```http
GET /t/f_avif,q_80/image.jpg
```

### Response
#### Success Response (200)
- **image** (binary) - The optimized image in the manually specified format and quality.

#### Response Example
(Binary image data, typically served with `Content-Type` header indicating the format, e.g., `image/avif`)
```

--------------------------------

### Video Transformation API Endpoints

Source: https://docs.openinary.dev/media-transformations/video-transformations

This section details various use cases for the Video Transformation API, demonstrating how to generate different video formats and qualities by manipulating URL parameters.

```APIDOC
## GET /t/w_1080,h_1080,q_85/social.mp4

### Description
Creates square videos optimized for social media feeds like Instagram and X.

### Method
GET

### Endpoint
/t/w_1080,h_1080,q_85/social.mp4

### Parameters
#### Query Parameters
- **w** (integer) - Required - Width of the video.
- **h** (integer) - Required - Height of the video.
- **q** (integer) - Required - Quality setting for the video.

### Request Example
```http
GET /t/w_1080,h_1080,q_85/social.mp4
```

### Response
#### Success Response (200)
- **video_content** (binary) - The transformed video file.

#### Response Example
(Binary video data)

---

## GET /t/w_640,h_360,q_65/video.mp4

### Description
Generates low-bandwidth versions of videos suitable for mobile users on slower internet connections.

### Method
GET

### Endpoint
/t/w_640,h_360,q_65/video.mp4

### Parameters
#### Query Parameters
- **w** (integer) - Required - Width of the video.
- **h** (integer) - Required - Height of the video.
- **q** (integer) - Required - Quality setting for the video.

### Request Example
```http
GET /t/w_640,h_360,q_65/video.mp4
```

### Response
#### Success Response (200)
- **video_content** (binary) - The transformed video file.

#### Response Example
(Binary video data)

---

## GET /t/w_1920,h_1080,q_95/presentation.mp4

### Description
Maintains maximum quality for professional presentations and demonstration videos.

### Method
GET

### Endpoint
/t/w_1920,h_1080,q_95/presentation.mp4

### Parameters
#### Query Parameters
- **w** (integer) - Required - Width of the video.
- **h** (integer) - Required - Height of the video.
- **q** (integer) - Required - Quality setting for the video.

### Request Example
```http
GET /t/w_1920,h_1080,q_95/presentation.mp4
```

### Response
#### Success Response (200)
- **video_content** (binary) - The transformed video file.

#### Response Example
(Binary video data)

---

## GET /t/w_400,h_300,so_5,eo_12/video.mp4

### Description
Extracts a specific segment from a video, resizing it to the specified dimensions. This is useful for creating highlights, previews, or short clips.

### Method
GET

### Endpoint
/t/w_400,h_300,so_5,eo_12/video.mp4

### Parameters
#### Query Parameters
- **w** (integer) - Required - Width of the video segment.
- **h** (integer) - Required - Height of the video segment.
- **so** (integer) - Required - Start offset in seconds.
- **eo** (integer) - Required - End offset in seconds.

### Request Example
```http
GET /t/w_400,h_300,so_5,eo_12/video.mp4
```

### Response
#### Success Response (200)
- **video_content** (binary) - The transformed video segment.

#### Response Example
(Binary video data)

---

## GET /t/w_400,h_300,so_5,f_webp/video.mp4

### Description
Generates a thumbnail image from a video by extracting a single frame at a specified timestamp. Supports different image formats like WebP, JPEG, and PNG.

### Method
GET

### Endpoint
/t/w_400,h_300,so_5,f_webp/video.mp4

### Parameters
#### Query Parameters
- **w** (integer) - Required - Width of the thumbnail.
- **h** (integer) - Required - Height of the thumbnail.
- **so** (integer) - Required - Timestamp in seconds from which to extract the frame.
- **f** (string) - Required - Format of the thumbnail image (e.g., webp, jpeg, png).

### Request Example
```http
GET /t/w_400,h_300,so_5,f_webp/video.mp4
```

### Response
#### Success Response (200)
- **image_content** (binary) - The generated thumbnail image.

#### Response Example
(Binary image data)
```

--------------------------------

### Supported Image Formats

Source: https://docs.openinary.dev/media-transformations/image-transformations

Details the image formats supported for both input and output, outlining the capabilities of each.

```APIDOC
## Supported Image Formats

### Input Formats
The system accepts the following image formats as input:

*   **JPEG / JPG**: Standard photo format.
*   **PNG**: With full transparency support.
*   **WebP**: Modern web format.
*   **AVIF**: Next-generation format.
*   **GIF**: First frame only (static output).

### Output Formats
Images can be delivered in these optimized formats:

*   **AVIF**: Modern format with best compression (up to 50% smaller than JPEG).
*   **WebP**: Modern format with excellent browser support.
*   **JPEG**: Universal compatibility across all devices.
*   **PNG**: Lossless compression with transparency support.

> **Note**: If no format is specified, the system automatically selects the optimal format based on browser support and content type.
```

--------------------------------

### Web-optimized landscape photo

Source: https://docs.openinary.dev/media-transformations/image-transformations

Delivers a full HD landscape photo in AVIF format, offering superior compression and quality for web use.

```APIDOC
## GET /t/w_1920,h_1080,q_85,f_avif/landscape.jpg

### Description
Generates a landscape image in Full HD resolution (1920x1080 pixels) using the AVIF format (`f_avif`) for maximum compression. The quality is set to 85 (`q_85`).

### Method
GET

### Endpoint
/t/w_1920,h_1080,q_85,f_avif/landscape.jpg

### Parameters
#### Path Parameters
- **w_1920** (integer) - Width of the image in pixels, set to 1920.
- **h_1080** (integer) - Height of the image in pixels, set to 1080.
- **q_85** (integer) - Quality setting, ranging from 0 to 100, with 85 providing a good balance.
- **f_avif** (string) - Output format set to AVIF for superior compression.

### Request Example
```http
GET /t/w_1920,h_1080,q_85,f_avif/landscape.jpg
```

### Response
#### Success Response (200)
- **image_data** (binary) - The optimized landscape image data in AVIF format.
```

--------------------------------

### HTTP Request for Forced WebP Format

Source: https://docs.openinary.dev/media-transformations/intelligent-compression

This HTTP request shows how to explicitly request WebP format for an image. This is typically used when specific compatibility needs dictate the use of WebP over other formats, overriding the automatic optimization.

```http
GET /t/f_webp,q_85/image.jpg
```

--------------------------------

### Web-Optimized Landscape Photo (HTTP)

Source: https://docs.openinary.dev/media-transformations/image-transformations

Delivers a web-optimized landscape photo in AVIF format for maximum compression and quality. This is suitable for full HD content.

```http
GET /t/w_1920,h_1080,q_85,f_avif/landscape.jpg
```

--------------------------------

### Image Transformations API

Source: https://docs.openinary.dev/media-transformations/image-transformations

This API allows you to transform images by specifying various parameters in the URL. You can control dimensions, cropping, aspect ratio, rotation, background, quality, and output format.

```APIDOC
## Image Transformations API

### Description
This API enables dynamic image manipulation through URL parameters. You can resize, crop, rotate, and optimize images with powerful URL-based parameters.

### Method
GET

### Endpoint
`/t/[parameters]/[image_path]`

### Parameters
#### Query Parameters
- **w** (integer) - Optional - Image width in pixels.
- **h** (integer) - Optional - Image height in pixels.
- **c** (string) - Optional - Crop mode for resizing. Available modes: `fill` (default), `fit`, `scale`, `crop`, `pad`.
- **ar** (string) - Optional - Aspect ratio (format: `W:H`). Examples: `ar_16:9`, `ar_1:1`, `ar_4:3`.
- **a** (string | number) - Optional - Rotation angle in degrees (`0-360`) or `auto` for EXIF-based rotation.
- **g** (string) - Optional - Focal point for cropping. Available positions: `center` (default), `north`, `south`, `east`, `west`, `face`, `auto`.
- **b** (string) - Optional - Background color for rotation or pad crop mode. Format: `b_rgb:ffffff`.
- **q** (integer) - Optional - Compression quality level (1-100). Default: 85.
- **f** (string) - Optional - Output format. Available formats: `avif`, `webp`, `jpeg`, `jpg`, `png`.

### Request Example
```http
GET /t/w_800,h_600,c_fill,f_webp,q_80/image.jpg
```

### Response
#### Success Response (200)
- **image** (binary) - The transformed image data.

#### Response Example
*(Binary image data would be returned here, not a JSON object)*
```

--------------------------------

### Rotated Logo with Transparency (HTTP)

Source: https://docs.openinary.dev/media-transformations/image-transformations

Rotates a logo image by a specified degree while preserving transparency. PNG format is ideal for this.

```http
GET /t/a_15,w_200,h_200/logo.png
```

--------------------------------

### Instagram-optimized portrait

Source: https://docs.openinary.dev/media-transformations/image-transformations

Generates a perfectly square image optimized for Instagram, with face-focused cropping and WebP output.

```APIDOC
## GET /t/ar_1:1,w_1080,h_1080,g_face,q_85,f_webp/portrait.jpg

### Description
Generates a perfectly square image (1:1 aspect ratio) with a width and height of 1080 pixels. It uses face-detection (`g_face`) to ensure faces are centered and applies a quality setting of 85 (`q_85`) with WebP format (`f_webp`) for optimal social media performance.

### Method
GET

### Endpoint
/t/ar_1:1,w_1080,h_1080,g_face,q_85,f_webp/portrait.jpg

### Parameters
#### Path Parameters
- **ar_1:1** (string) - Aspect ratio, set to 1:1 for a square image.
- **w_1080** (integer) - Width of the image in pixels, set to 1080.
- **h_1080** (integer) - Height of the image in pixels, set to 1080.
- **g_face** (string) - Enables face detection for cropping, ensuring faces remain in focus.
- **q_85** (integer) - Quality setting, ranging from 0 to 100, with 85 providing a good balance.
- **f_webp** (string) - Output format set to WebP for modern browser optimization.

### Request Example
```http
GET /t/ar_1:1,w_1080,h_1080,g_face,q_85,f_webp/portrait.jpg
```

### Response
#### Success Response (200)
- **image_data** (binary) - The optimized image data in WebP format.
```

--------------------------------

### Instagram-optimized Portrait (HTTP)

Source: https://docs.openinary.dev/media-transformations/image-transformations

Generates an Instagram-optimized square portrait image. It uses face-focused cropping and WebP format for social media.

```http
GET /t/ar_1:1,w_1080,h_1080,g_face,q_85,f_webp/portrait.jpg
```

--------------------------------

### Rotated logo with transparency

Source: https://docs.openinary.dev/media-transformations/image-transformations

Rotates a logo image by a specified degree while preserving transparency, suitable for various design applications.

```APIDOC
## GET /t/a_15,w_200,h_200/logo.png

### Description
Rotates a logo image by 15 degrees (`a_15`) and resizes it to 200x200 pixels (`w_200,h_200`). The PNG format automatically preserves transparency.

### Method
GET

### Endpoint
/t/a_15,w_200,h_200/logo.png

### Parameters
#### Path Parameters
- **a_15** (integer) - Rotation angle in degrees, set to 15.
- **w_200** (integer) - Width of the image in pixels, set to 200.
- **h_200** (integer) - Height of the image in pixels, set to 200.

### Request Example
```http
GET /t/a_15,w_200,h_200/logo.png
```

### Response
#### Success Response (200)
- **image_data** (binary) - The rotated logo image data in PNG format.
```
Tokens:
Raw