Skip to main content

​
Presets (Pro)

Presets are a Pro feature. Upgrade to Pro to use them.
Presets let you save transformation configurations and apply them with a simple URL parameter. Instead of long URLs with multiple parameters, use ?p:thumbnail or ?p:hero.

​
Why Use Presets?

  • Consistency: Same transformations across your application
  • Simplicity: Short, readable URLs
  • Maintainability: Update transformations in one place
  • Performance: Preset lookup is cached at the edge

​
Available Parameters

Presets support all image transformation parameters. Here’s the complete reference:

​
Size & Layout

ParameterTypeDescriptionValuesDefault
wintegerWidth in pixels1-10000Auto
hintegerHeight in pixels1-10000Auto
fitstringHow the image fits within dimensionsSee belowcover
aspectstringAspect ratio constraintSee beloworiginal
Fit mode values:
ValueDescription
coverFill the dimensions, cropping excess (default)
containFit within dimensions, preserving aspect ratio (may have letterboxing)
fillStretch to fill dimensions exactly (may distort)
scale-downLike contain, but never upscale smaller images
Aspect ratio values:
ValueDescription
originalKeep original aspect ratio (default)
1:1Square
4:3Standard photo
16:9Widescreen
3:2Classic 35mm
21:9Ultra-wide

​
Quality & Display

ParameterTypeDescriptionValuesDefault
qintegerCompression quality1-10080
dprnumberDevice pixel ratio (Retina)1, 1.5, 2, 31
cropstringCrop position when using fit=coverSee belowcenter
grayscalebooleanConvert to grayscaletrue, falsefalse
Crop position values:
ValueDescription
centerCenter of the image (default)
topTop edge
bottomBottom edge
leftLeft edge
rightRight edge
top-leftTop-left corner
top-rightTop-right corner
bottom-leftBottom-left corner
bottom-rightBottom-right corner
attentionAuto-detect important area (faces, objects)
entropyArea with highest visual complexity

​
Effects & Transform

ParameterTypeDescriptionValuesDefault
blurnumberGaussian blur radius0-1000 (none)
sharpennumberSharpen intensity0-1000 (none)
rotateintegerRotation angle0, 90, 180, 270, auto0 (none)
flipstringFlip/mirror the imageh, v, bothnone
Rotate values:
ValueDescription
0No rotation (default)
90Rotate 90° clockwise
180Rotate 180°
270Rotate 270° clockwise (90° counter-clockwise)
autoAuto-rotate based on EXIF orientation
Flip values:
ValueDescription
hFlip horizontally (mirror)
vFlip vertically
bothFlip both horizontally and vertically

​
Example: All Parameters

{
  "name": "full-example",
  "description": "Example with all parameters",
  "params": {
    "w": 800,
    "h": 600,
    "fit": "cover",
    "aspect": "16:9",
    "q": 85,
    "dpr": 2,
    "crop": "attention",
    "grayscale": false,
    "blur": 0,
    "sharpen": 10,
    "rotate": "auto",
    "flip": null
  }
}

​
Common Preset Configurations

{
  "name": "thumbnail-2x",
  "params": {
    "w": 200,
    "h": 200,
    "fit": "cover",
    "crop": "attention",
    "dpr": 2,
    "q": 80
  }
}

{
  "name": "portrait-bw",
  "params": {
    "w": 400,
    "h": 500,
    "fit": "cover",
    "crop": "attention",
    "grayscale": true,
    "sharpen": 15
  }
}

{
  "name": "blurred-bg",
  "params": {
    "w": 1920,
    "h": 1080,
    "fit": "cover",
    "blur": 20,
    "q": 60
  }
}

{
  "name": "social-wide",
  "params": {
    "w": 1200,
    "aspect": "16:9",
    "fit": "cover",
    "crop": "attention",
    "q": 85
  }
}
You don’t need to specify all parameters. Omitted parameters use default values or are auto-calculated (e.g., height is auto-calculated if only width is provided).

​
Creating a Preset

curl -X POST https://api.img-src.io/api/v1/settings/presets \
  -H "Authorization: Bearer imgsrc_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "thumbnail",
    "description": "200x200 square thumbnail",
    "params": {
      "w": 200,
      "h": 200,
      "fit": "cover",
      "q": 80
    }
  }'

​
Using a Preset

Apply a preset with the p: parameter. The syntax is p:preset_name (note the colon): 
<!-- Before: verbose URL -->
<img src="https://img-src.io/i/john/photo.jpg?w=200&h=200&fit=cover&q=80" />

<!-- After: clean preset URL -->
<img src="https://img-src.io/i/john/photo.jpg?p:thumbnail" />
The preset parameter uses p:name syntax (with a colon), not p=name. This is to clearly distinguish presets from other parameters.

​
Common Preset Examples

​
Thumbnail

{
  "name": "thumbnail",
  "params": {
    "w": 200,
    "h": 200,
    "fit": "cover",
    "q": 75
  }
}

​
Hero Image

{
  "name": "hero",
  "params": {
    "w": 1920,
    "h": 1080,
    "fit": "cover",
    "q": 90
  }
}

​
Product Image

{
  "name": "product",
  "params": {
    "w": 800,
    "h": 800,
    "fit": "contain",
    "q": 85
  }
}

​
Avatar

{
  "name": "avatar",
  "params": {
    "w": 100,
    "h": 100,
    "fit": "cover",
    "q": 80
  }
}

​
OG Image (Social Media)

{
  "name": "og",
  "params": {
    "w": 1200,
    "h": 630,
    "fit": "cover",
    "q": 85
  }
}

​
Overriding Preset Parameters

You can override specific parameters: 
<!-- Use thumbnail preset but higher quality -->
<img src="https://img-src.io/i/john/photo.jpg?p:thumbnail&q=95" />

<!-- Use hero preset but different size -->
<img src="https://img-src.io/i/john/photo.jpg?p:hero&w=1280&h=720" />

​
Listing Presets

curl https://api.img-src.io/api/v1/settings/presets \
  -H "Authorization: Bearer imgsrc_YOUR_API_KEY"

​
Updating a Preset

Updating a preset affects all future requests. Cached images using the old parameters will continue to be served until cache expires or is purged.
curl -X PUT https://api.img-src.io/api/v1/settings/presets/preset_abc123 \
  -H "Authorization: Bearer imgsrc_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "w": 250,
      "h": 250,
      "fit": "cover",
      "q": 80
    }
  }'

​
Deleting a Preset

After deletion, URLs using this preset will return a 400 error. Update your code first.
curl -X DELETE https://api.img-src.io/api/v1/settings/presets/thumbnail \
  -H "Authorization: Bearer imgsrc_YOUR_API_KEY"

​
Preset Naming Rules

  • Alphanumeric characters, hyphens, and underscores
  • 1-50 characters
  • Case-sensitive
  • Must be unique per user
Valid names:
  • thumbnail
  • hero-image
  • product_large
  • og_1200x630
Invalid names:
  • my preset (spaces)
  • @avatar (special characters)
  • “ (empty)

​
Limits

PlanMax Presets
Pro50

​
Best Practices

Name presets by their purpose, not their parameters:
  • Good: hero, thumbnail, product-card
  • Bad: 200x200, small, img1
Use the description field to explain when to use each preset.
Create presets for your most frequently used transformations first.
Verify preset output before using in production:
curl -I "https://img-src.io/i/username/test.jpg?p:my-preset"