Transform

Three operations cover geometric and tonal transformations: Rotate changes orientation, Watermark composites text or an image overlay, and Adjust modifies tonal properties such as brightness, contrast, and blur.

Rotate

Rotate an image by a fixed angle or an arbitrary float angle, optionally flip it, and fill any exposed canvas area with a background color.

Parameters

operation

string

required

Must be "rotate".

input

string

required

Path to the source image.

output

string

required

Path for the rotated output file.

angle

number

Fixed rotation angle in degrees. Accepted values: 0, 90, 180, 270. Either angle or angle_f is required (unless using auto_orient or flip alone).

angle_f

number

Arbitrary rotation angle in degrees. Range: -360 to 360. Exposed canvas corners are filled with background. Either angle or angle_f is required.

flip

string

Mirror the image. "horizontal" reflects left-to-right; "vertical" reflects top-to-bottom. Can be combined with angle or angle_f.

auto_orient

boolean

default:"false"

When true, reads the EXIF orientation tag and applies the corresponding transformation so the image displays correctly, then strips that tag.

background

string

default:"transparent"

Background fill color for canvas areas exposed by non-90° rotation. Hex format: "#RRGGBB".

format

string

default:"same as input"

Output format: png, jpeg, webp, or avif.

quality

number

default:"85"

Encode quality for JPEG and WebP outputs. Range: 1–100.

inline

boolean

default:"false"

When true, the output is also returned as a base64-encoded string in data_base64.

Go client

func (c *Client) Rotate(ctx context.Context, job *RotateJob) (*JobResult, error)

type RotateJob struct {
    Operation  string   `json:"operation"`
    Input      string   `json:"input"`
    Output     string   `json:"output"`
    Angle      *uint16  `json:"angle,omitempty"`
    AngleF     *float64 `json:"angle_f,omitempty"`
    Flip       string   `json:"flip,omitempty"`
    AutoOrient bool     `json:"auto_orient,omitempty"`
    Background string   `json:"background,omitempty"`
    Format     string   `json:"format,omitempty"`
    Quality    *uint8   `json:"quality,omitempty"`
    Inline     bool     `json:"inline,omitempty"`
}

Examples

{
  "operation": "rotate",
  "input": "photo.jpg",
  "output": "rotated.jpg",
  "angle": 90,
  "format": "jpeg",
  "quality": 90
}

Go examples

client := dpf.NewClient("/usr/local/bin/dpf")

// Rotate 90°
angle := uint16(90)
result, err := client.Rotate(ctx, &dpf.RotateJob{
    Input:  "photo.jpg",
    Output: "rotated.jpg",
    Angle:  &angle,
})

// Flip horizontal
result, err = client.Rotate(ctx, &dpf.RotateJob{
    Input:  "photo.jpg",
    Output: "flipped.jpg",
    Flip:   "horizontal",
})

// Auto-orient from EXIF
result, err = client.Rotate(ctx, &dpf.RotateJob{
    Input:      "photo.jpg",
    Output:     "oriented.jpg",
    AutoOrient: true,
})

Watermark

Composite a text string or an image file over a source image, controlling position, opacity, and offset.

Parameters

operation

string

required

Must be "watermark".

input

string

required

Path to the source image.

output

string

required

Path for the watermarked output file.

text

string

Text string to render as the watermark. Either text or image is required.

image

string

Path to an image file to composite as the watermark. Either text or image is required.

position

string

default:"bottom-right"

Position of the watermark on the canvas. See the position grid below.

opacity

number

default:"1.0"

Watermark opacity. Range: 0.0 (fully transparent) to 1.0 (fully opaque).

font_size

number

default:"24"

Font size in pixels for text watermarks.

color

string

default:"#FFFFFF"

Text color in hex format "#RRGGBB". Applies to text watermarks only.

offset_x

number

default:"10"

Horizontal offset from the nearest edge in pixels.

offset_y

number

default:"10"

Vertical offset from the nearest edge in pixels.

format

string

default:"same as input"

Output format: png, jpeg, webp, or avif.

quality

number

default:"85"

Encode quality for JPEG and WebP outputs. Range: 1–100.

inline

boolean

default:"false"

When true, the output is also returned as a base64-encoded string in data_base64.

Position grid

The position field accepts a value from the 3×3 grid below:

	Left	Center	Right
Top	`top-left`	`top-center`	`top-right`
Middle	`center-left`	`center`	`center-right`
Bottom	`bottom-left`	`bottom-center`	`bottom-right`

Short aliases (top, bottom, left, right, middle) are also accepted.

Go client

func (c *Client) Watermark(ctx context.Context, job *WatermarkJob) (*JobResult, error)

type WatermarkJob struct {
    Operation string   `json:"operation"`
    Input     string   `json:"input"`
    Output    string   `json:"output"`
    Text      string   `json:"text,omitempty"`
    Image     string   `json:"image,omitempty"`
    Position  string   `json:"position,omitempty"`
    Opacity   *float64 `json:"opacity,omitempty"`
    FontSize  *uint32  `json:"font_size,omitempty"`
    Color     string   `json:"color,omitempty"`
    OffsetX   *uint32  `json:"offset_x,omitempty"`
    OffsetY   *uint32  `json:"offset_y,omitempty"`
    Format    string   `json:"format,omitempty"`
    Quality   *uint8   `json:"quality,omitempty"`
    Inline    bool     `json:"inline,omitempty"`
}

Examples

{
  "operation": "watermark",
  "input": "photo.jpg",
  "output": "watermarked.jpg",
  "text": "© 2024 DevPixelForge",
  "position": "bottom-right",
  "opacity": 0.7,
  "font_size": 24,
  "color": "#FFFFFF",
  "offset_x": 20,
  "offset_y": 20
}

Go examples

client := dpf.NewClient("/usr/local/bin/dpf")

opacity := float64(0.7)
fontSize := uint32(24)
offsetX := uint32(20)
offsetY := uint32(20)

// Text watermark
result, err := client.Watermark(ctx, &dpf.WatermarkJob{
    Input:    "photo.jpg",
    Output:   "watermarked.jpg",
    Text:     "© 2024 DevPixelForge",
    Position: "bottom-right",
    Opacity:  &opacity,
    FontSize: &fontSize,
    Color:    "#FFFFFF",
    OffsetX:  &offsetX,
    OffsetY:  &offsetY,
})

// Image watermark
imgOpacity := float64(0.5)
result, err = client.Watermark(ctx, &dpf.WatermarkJob{
    Input:    "photo.jpg",
    Output:   "watermarked.jpg",
    Image:    "logo.png",
    Position: "top-right",
    Opacity:  &imgOpacity,
})

Adjust

Modify tonal and focus properties of an image: brightness, contrast, saturation, Gaussian blur, and sharpening.

Parameters

operation

string

required

Must be "adjust".

input

string

required

Path to the source image.

output

string

required

Path for the adjusted output file.

brightness

number

default:"0.0"

Brightness adjustment. Range: -1.0 (fully black) to 1.0 (fully white). 0.0 means no change.

contrast

number

default:"0.0"

Contrast adjustment. Range: -1.0 to 1.0. 0.0 means no change.

saturation

number

default:"0.0"

Saturation adjustment. Range: -1.0 (grayscale) to 1.0 (maximum saturation). 0.0 means no change.

blur

number

Gaussian blur sigma. Range: 0.0 to 50.0. Omit or set to null for no blur.

sharpen

number

Sharpening amount. Range: 0.0 to 10.0. Omit or set to null for no sharpening.

linear_rgb

boolean

default:"true"

When true (the default), tonal adjustments are applied in linear light. Produces perceptually correct results for brightness and contrast changes.

format

string

default:"same as input"

Output format: png, jpeg, webp, or avif.

quality

number

default:"85"

Encode quality for JPEG and WebP outputs. Range: 1–100.

inline

boolean

default:"false"

When true, the output is also returned as a base64-encoded string in data_base64.

Go client

func (c *Client) Adjust(ctx context.Context, job *AdjustJob) (*JobResult, error)

type AdjustJob struct {
    Operation  string   `json:"operation"`
    Input      string   `json:"input"`
    Output     string   `json:"output"`
    Brightness *float64 `json:"brightness,omitempty"`
    Contrast   *float64 `json:"contrast,omitempty"`
    Saturation *float64 `json:"saturation,omitempty"`
    Blur       *float64 `json:"blur,omitempty"`
    Sharpen    *float64 `json:"sharpen,omitempty"`
    LinearRGB  bool     `json:"linear_rgb,omitempty"`
    Format     string   `json:"format,omitempty"`
    Quality    *uint8   `json:"quality,omitempty"`
    Inline     bool     `json:"inline,omitempty"`
}

Examples

{
  "operation": "adjust",
  "input": "photo.jpg",
  "output": "adjusted.jpg",
  "brightness": 0.15,
  "contrast": 0.1,
  "format": "jpeg",
  "quality": 90
}

Go examples

client := dpf.NewClient("/usr/local/bin/dpf")

brightness := float64(0.15)
contrast := float64(0.1)

// Brightness and contrast
result, err := client.Adjust(ctx, &dpf.AdjustJob{
    Input:      "photo.jpg",
    Output:     "adjusted.jpg",
    Brightness: &brightness,
    Contrast:   &contrast,
    Format:     "jpeg",
})

// Grayscale conversion via saturation
saturation := float64(-1.0)
result, err = client.Adjust(ctx, &dpf.AdjustJob{
    Input:      "photo.jpg",
    Output:     "grayscale.jpg",
    Saturation: &saturation,
})

// Blur for thumbnail background
blur := float64(20.0)
result, err = client.Adjust(ctx, &dpf.AdjustJob{
    Input:  "photo.jpg",
    Output: "blurred-bg.jpg",
    Blur:   &blur,
})

Image Operations

Video Operations

Audio Operations

Protocol Reference

Rotate

Parameters

Go client

Examples

Watermark

Parameters

Position grid

Go client

Examples

Adjust

Parameters

Go client

Examples

Build docs developers (and LLMs) love

Image Operations

Video Operations

Audio Operations

Protocol Reference

​Rotate

​Parameters

​Go client

​Examples

​Watermark

​Parameters

​Position grid

​Go client

​Examples

​Adjust

​Parameters

​Go client

​Examples

Build docs developers (and LLMs) love

Rotate

Parameters

Go client

Examples

Watermark

Parameters

Position grid

Go client

Examples

Adjust

Parameters

Go client

Examples