Resize and transform images

You attach an image manipulation policy and create a named resize variant.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Prerequisites

• Balancer access and a key in the BALANCER_API_KEY environment variable with permission for these operations.
• The API host shown in the Balancer portal. Replace <your-api-host> in every example with that host.
• A shell, curl and Python 3 for examples that build JSON from environment variables.
• An HTTP group, a supported source image and an image policy. Set IMAGE_MANIPULATION_POLICY_ID to your policy identifier. Export IMAGE_RESIZE_OPS with your accepted width and height operations string. TODO(verify): The exact separator grammar for a runnable width and height operations string.

Resource identifiers come from your API responses. Set each variable when its value is available, before the first step that uses it.

Environment variable	Value
GROUP_ID	Returned resource identifier, or your selected scope identifier.
HTTP_LB_ID	Returned resource identifier, or your selected scope identifier.
IMAGE_MANIPULATION_POLICY_ID	Returned resource identifier, or your selected scope identifier.
IMAGE_RESIZE_OPS	Your accepted configuration value.

For an identifier, enter the value returned for your resource and export it:

read -r -p 'GROUP_ID: ' GROUP_ID
export GROUP_ID

Steps

1. Create a policy if needed.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/image-manipulation-policies" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"name":"site_images"}'

   API reference: Create a new reusable image manipulation policy

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "imageManipulationPolicyId": 1
     }
   }

   Set IMAGE_MANIPULATION_POLICY_ID to the returned imageManipulationPolicyId.

2. Create a resize variant.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/image-manipulation-policies/$IMAGE_MANIPULATION_POLICY_ID/variants" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'name': 'thumbnail', 'canonicalOpsString': os.environ['IMAGE_RESIZE_OPS']}))
   PYBODY

   API reference: Create a new named image manipulation variant inside one policy

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "imageManipulationVariantId": 1
     }
   }

3. Enable image handling and assign the default variant.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request PATCH \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'imageManipulationEnabled': True, 'imageManipulationPolicyId': int(os.environ['IMAGE_MANIPULATION_POLICY_ID']), 'imageManipulationPrefix': '/i', 'defaultImageManipulationVariant': 'thumbnail'}))
   PYBODY

   API reference: Update an HTTP group configuration

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

4. Read the policy and its variants.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/image-manipulation-policies/$IMAGE_MANIPULATION_POLICY_ID" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Get one image manipulation policy

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "imageManipulationPolicyId": 1
     }
   }

5. Read the group assignment.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Get HTTP group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

Verify

Inspect the returned image dimensions and Content-Type. A 200 alone does not establish transformation. Compare image statistics for the test window with the selected variant. TODO(verify): The complete public request URL grammar for a named variant and source image.

An API mutation saves desired configuration first. Readback and a live traffic check answer different questions. No fixed propagation time is established.

Troubleshooting

Symptom	Cause	Fix
Dimensions differ	DPR scaling, fit mode or variant differs	Check the effective variant and output dimensions.
Request is rejected	Operation, codec or policy bound disallows it	Check enabled operations, formats and input size.
Expected WAF match is absent	Image handling uses a separate request path	Verify image behavior separately from ordinary WAF inspection.

Limits and defaults

Setting	Limit or default
Policies per account	50
Variants per policy	100
Width and height	Maximum 8192 each, after DPR scaling
Output pixels	Maximum 100000000
Input bytes	Maximum 67108864
Prefix	Default /i
Fit and gravity	Default cover and centre
Format and metadata	Default auto and strip
Lossy quality	Default 85
Variant operations string	Maximum 256 characters

API status codes

Status	Meaning
200	Request succeeds; inspect returned data.
400	Invalid arguments or configuration.
401	Authentication or authorization denied.
404	Resource or parent is unavailable.
409	Resource state conflicts with the operation.
412	Inspect the returned error details.
500	The request encounters a server error.

Related API operations

• DELETE /image-manipulation-policies/{imageManipulationPolicyId}
• DELETE /image-manipulation-policies/{imageManipulationPolicyId}/variants/{imageManipulationVariantId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}
• GET /image-manipulation-policies
• GET /image-manipulation-policies/{imageManipulationPolicyId}
• GET /image-manipulation-policies/{imageManipulationPolicyId}/variants
• GET /image-manipulation-policies/{imageManipulationPolicyId}/variants/{imageManipulationVariantId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}
• PATCH /image-manipulation-policies/{imageManipulationPolicyId}
• PATCH /image-manipulation-policies/{imageManipulationPolicyId}/variants/{imageManipulationVariantId}
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/image-manipulation/statistics
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/image-manipulation/statistics
• POST /http-loadbalancers/{httpLbId}/image-manipulation/statistics
• POST /image-manipulation-policies
• POST /image-manipulation-policies/{imageManipulationPolicyId}/variants

API reference

• Delete an image manipulation policy

• Delete an image manipulation variant

• Get HTTP group

• List image manipulation policies

• Get one image manipulation policy

• List variants for one image manipulation policy

• Get one image manipulation variant

• Update an HTTP group configuration

• Update an image manipulation policy

• Update an image manipulation variant

• Query image manipulation statistics for an HTTP group

• Query image manipulation statistics for an HTTP route

• Query image manipulation statistics for an HTTP load balancer

• Create a new reusable image manipulation policy

• Create a new named image manipulation variant inside one policy

• HTTP Load Balancers

• Groups and Routes

• Image Manipulation Policies

Need Help?

Contact your account manager or use the Balancer portal.