Image Operations

Process images with resize, optimize, watermark, color extraction, and AI-powered keyword generation.

Resize Image

POST /api/v1/jobs/image/resize

Resize an image to specific dimensions.

Request Body

{
  "source_bucket": "my-bucket",
  "source_key": "images/photo.jpg",
  "dest_bucket": "my-bucket",
  "dest_key": "images/photo-800x600.jpg",
  "width": 800,
  "height": 600,
  "format": "jpeg",
  "quality": 85
}

Parameters

Parameter	Type	Required	Description
source_bucket	string	✅	Source S3 bucket
source_key	string	✅	Source S3 key
dest_bucket	string	✅	Destination S3 bucket
dest_key	string	✅	Destination S3 key
width	integer	✅	Target width in pixels (min: 1)
height	integer	✅	Target height in pixels (min: 1)
format	string	❌	Output format: jpeg, png, webp, avif
quality	integer	❌	Quality 1-100 (default: 85)

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job queued for processing"
}

Example

cURL

curl -X POST http://localhost:8080/api/v1/jobs/image/resize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "photo.jpg",
    "dest_bucket": "my-bucket",
    "dest_key": "photo-resized.jpg",
    "width": 1920,
    "height": 1080
  }'

JavaScript

const response = await fetch('http://localhost:8080/api/v1/jobs/image/resize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    source_bucket: 'my-bucket',
    source_key: 'photo.jpg',
    dest_bucket: 'my-bucket',
    dest_key: 'photo-resized.jpg',
    width: 1920,
    height: 1080
  })
});
const data = await response.json();

Python

import requests

response = requests.post(
    'http://localhost:8080/api/v1/jobs/image/resize',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key_here'
    },
    json={
        'source_bucket': 'my-bucket',
        'source_key': 'photo.jpg',
        'dest_bucket': 'my-bucket',
        'dest_key': 'photo-resized.jpg',
        'width': 1920,
        'height': 1080
    }
)
data = response.json()

---

Optimize Image

POST /api/v1/jobs/image/optimize

Compress and optimize an image, optionally converting to modern formats like WebP or AVIF.

Request Body

{
  "source_bucket": "my-bucket",
  "source_key": "images/photo.jpg",
  "dest_bucket": "my-bucket",
  "dest_key": "images/photo-optimized.webp",
  "format": "webp",
  "quality": 80,
  "strip_metadata": true
}

Parameters

Parameter	Type	Required	Description
source_bucket	string	✅	Source S3 bucket
source_key	string	✅	Source S3 key
dest_bucket	string	✅	Destination S3 bucket
dest_key	string	✅	Destination S3 key
format	string	❌	Output format: jpeg, png, webp, avif
quality	integer	❌	Quality 1-100 (default: 80)
strip_metadata	boolean	❌	Remove EXIF data (default: false)

Example

curl -X POST http://localhost:8080/api/v1/jobs/image/optimize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "photo.jpg",
    "dest_bucket": "my-bucket",
    "dest_key": "photo.webp",
    "format": "webp",
    "quality": 85,
    "strip_metadata": true
  }'

Format Recommendations

• WebP: Best balance of quality and file size, widely supported
• AVIF: Superior compression, growing browser support
• JPEG: Universal compatibility, good for photos
• PNG: Lossless, best for graphics with transparency

---

Add Watermark

POST /api/v1/jobs/image/watermark

Add text or image watermark to an image.

Request Body

{
  "source_bucket": "my-bucket",
  "source_key": "images/photo.jpg",
  "dest_bucket": "my-bucket",
  "dest_key": "images/photo-watermarked.jpg",
  "watermark_text": "© 2025 My Company",
  "position": "bottom-right",
  "opacity": 70
}

Parameters

Parameter	Type	Required	Description
source_bucket	string	✅	Source S3 bucket
source_key	string	✅	Source S3 key
dest_bucket	string	✅	Destination S3 bucket
dest_key	string	✅	Destination S3 key
watermark_text	string	❌	Text to overlay (mutually exclusive with watermark_image)
watermark_image	string	❌	S3 key to watermark image
position	string	❌	Position: top-left, top-right, bottom-left, bottom-right, center
opacity	integer	❌	Opacity 0-100 (default: 100)

Example with Text Watermark

curl -X POST http://localhost:8080/api/v1/jobs/image/watermark \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "photo.jpg",
    "dest_bucket": "my-bucket",
    "dest_key": "photo-watermarked.jpg",
    "watermark_text": "© 2025 My Brand",
    "position": "bottom-right",
    "opacity": 70
  }'

Example with Image Watermark

curl -X POST http://localhost:8080/api/v1/jobs/image/watermark \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "photo.jpg",
    "dest_bucket": "my-bucket",
    "dest_key": "photo-watermarked.jpg",
    "watermark_image": "watermarks/logo.png",
    "position": "center",
    "opacity": 50
  }'

---

Extract Dominant Colors

POST /api/v1/jobs/image/colors

Extract dominant colors from an image for theming, search, or UI generation.

Request Body

{
  "source_bucket": "my-bucket",
  "source_key": "images/photo.jpg",
  "color_count": 5,
  "format": "hex"
}

Parameters

Parameter	Type	Required	Description
source_bucket	string	✅	Source S3 bucket
source_key	string	✅	Source S3 key
color_count	integer	❌	Number of colors to extract (3-10, default: 5)
format	string	❌	Color format: hex, rgb, hsl (default: hex)

Response

After job completion, the result will contain:

{
  "colors": [
    "#3B82F6",
    "#10B981",
    "#F59E0B",
    "#EF4444",
    "#8B5CF6"
  ],
  "percentages": [35.2, 28.1, 18.5, 12.3, 5.9]
}

Example

curl -X POST http://localhost:8080/api/v1/jobs/image/colors \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "photo.jpg",
    "color_count": 5,
    "format": "hex"
  }'

Use Cases

• Generate color palettes for design systems
• Create themed UI based on image colors
• Improve image search with color filters
• Automatic categorization by color

---

Generate AI Keywords

POST /api/v1/jobs/image/ai/keywords

Generate searchable keywords for an image using AI vision models.

Request Body

{
  "source_bucket": "my-bucket",
  "source_key": "images/photo.jpg",
  "keyword_count": 15,
  "language": "en"
}

Parameters

Parameter	Type	Required	Description
source_bucket	string	✅	Source S3 bucket
source_key	string	✅	Source S3 key
keyword_count	integer	❌	Number of keywords (10-20, default: 15)
language	string	❌	Language code (default: en)

Response

After job completion, the result will contain:

{
  "keywords": [
    "sunset",
    "beach",
    "ocean",
    "palm trees",
    "tropical",
    "vacation",
    "paradise",
    "coastline",
    "scenic",
    "nature"
  ],
  "confidence_scores": [0.95, 0.92, 0.89, 0.87, 0.85, ...]
}

Example

curl -X POST http://localhost:8080/api/v1/jobs/image/ai/keywords \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "photo.jpg",
    "keyword_count": 15,
    "language": "en"
  }'

AI Provider

This feature requires an external AI provider to be configured. See AI Features for setup instructions.

---

Common Use Cases

Responsive Images

Resize images to multiple dimensions for different screen sizes

Modern Formats

Convert to WebP/AVIF for better performance

Brand Protection

Add watermarks to protect intellectual property

Visual Search

Extract colors and keywords for searchability

Error Handling

Common Errors

• 400 Bad Request: Invalid dimensions, missing required fields
• 404 Not Found: Source file doesn’t exist in S3
• 500 Internal Error: Processing failed, check job status for details

Next Steps

• Learn about Video Operations
• Set up Webhooks for job notifications
• Explore Batch Processing for multiple images