Start with a source
Request workspace access, open the console and configure a Source with an approved HTTPS image origin. Test a relative image path, choose defaults and publish the source configuration.
Build an image URL
https://imgexo.com/{source-slug}/{image-path}
?w=800&fit=clip&auto=format,compressThe source selects your existing origin. The path selects an image inside it. Query parameters select the output. The example source and path are illustrative; replace them with your published source.
The parameters you’ll reach for first
w / h- Target width and height in pixels, bounded by the source’s configured limits.
fit- clip, max, crop, fill, fillmax, scale or min. Fit modes that need both dimensions require w and h.
crop- Crop position, including supported anchors and focalpoint.
fm- Explicit output format: avif, webp, jpg or png.
auto- format negotiates a browser-supported format; compress enables automatic compression defaults. Combine as auto=format,compress.
q- Quality setting. Use a valid value from 1 to 100 and compare the visual result.
dpr- Device-pixel ratio. The final dimensions remain subject to source limits.
bg / fill-color- Background color for supported fill operations.
fp-x / fp-y- Focal-point coordinates from 0 to 1; defaults 0.5 / 0.5. Use fit=crop and crop=focalpoint.
fp-z- Focal zoom from 1 to 100; default 1. Same parameter as Imgix.
fp-debug- Focal crosshair: true / 1 on, false / 0 off. See the Smart Focus guide for migration examples.
ar- W:H aspect ratio for crop and min. For example w=640 and ar=16:9 produces 640×360.
rect / rot / blur / sharp- Rectangle extraction, rotation, blur and sharpening within the implemented limits.
Compose text and a logo
Turn a source photo into a social card with one headline and one logo. Set a 1200 × 630 crop, place your logo at the top left and your headline at the bottom.
/shop/model.png?w=1200&h=630&fit=crop &txt=New%20Styles&txt-size=80&txt-color=fff &txt-align=bottom,center&txt-pad=48 &mark=%2Fbrand%2Flogo.png&mark-scale=22 &mark-align=top,left&mark-pad=48&auto=format,compress
txt accepts literal UTF-8 text, including Hebrew and line breaks, up to 1000 characters. txt-size is 1–512 pixels; txt-font selects an installed font, with a system fallback for unavailable fonts. Text wraps within the padded image; oversized text returns an error. txt-color is three- or six-digit RGB hex.
mark must be a PNG, JPEG, WebP or AVIF path in the same Source. The leading slash refers to that Source's root. Remote logo URLs, SVG and animated logos are unsupported. mark-scale sets logo width to 1–100% of the image width; mark-alpha sets opacity from 0–100 while preserving the original transparency. To make a logo white, use the encoded value mark=%2Flogo.png%3Fbri%3D100.
Both layers accept top/middle/bottom with left/center/right alignment, plus padding in logical pixels that scales with DPR. This supports one text layer and one logo layer. Indexed multi-layer parameters and the full Imgix typography API are outside this feature. Try the Text & logo tab in the live Playground.
Text and logo API examples
Use POST /v1/urls with a server-side API key scoped to urls:write. Pass text and logo settings in the transform object. Download the JSON request and replace the Source ID and image paths with your own.
JSON request
{
"sourceId": "source_shop",
"relativePath": "model.jpg",
"transform": {
"w": 1200,
"h": 630,
"fit": "crop",
"crop": "top",
"auto": ["format", "compress"],
"txt": "New Styles",
"txt-font": "DejaVu Sans Bold",
"txt-size": 80,
"txt-color": "fff",
"txt-align": "bottom,center",
"txt-pad": 48,
"mark": "/brand/logo.png?bri=100",
"mark-scale": 22,
"mark-align": "top,left",
"mark-pad": 48,
"mark-alpha": 100
}
}JSON values are unencoded. The logo path is relative to this Source, including the optional ?bri=100 for a white logo. Use the Source ID in API requests; use its slug in direct image URLs.
cURL
Set IMGEXO_API_KEY on your server and save the body as text-logo-request.json.
curl --request POST 'https://imgexo.com/v1/urls' \ --header "Authorization: Bearer $IMGEXO_API_KEY" \ --header 'Content-Type: application/json' \ --data-binary @text-logo-request.json
The response contains url, srcset and activeRevision. Without requested widths, srcset is empty. Open the returned URL to render the image. For signed Sources, use the returned URL unchanged. Keep your API key out of browser code and image URLs.
JavaScript · Hebrew headline
An unsigned compatibility-mode Source accepts an ordinary image URL without an API key. URLSearchParams encodes Hebrew and the nested logo query.
const query = new URLSearchParams({
w: "1200", h: "630", fit: "crop", crop: "top",
txt: "סגנונות חדשים", "txt-size": "80", "txt-color": "fff",
"txt-align": "bottom,center", "txt-pad": "48",
mark: "/brand/logo.png?bri=100", "mark-scale": "22",
"mark-align": "top,left", "mark-pad": "48", "mark-alpha": "100",
auto: "format,compress"
});
const imageUrl = `https://imgexo.com/shop/model.jpg?${query}`;The authenticated console URL endpoint accepts the same transform at POST /api/admin/v1/sources/{id}/urls. For a draft preview, use POST /api/admin/v1/sources/{id}/preview with {relativePath, transform, revision: "draft"}. A machine API key does not authorize console preview access.
Only a same-Source raster logo is accepted. Invalid transforms return 400; invalid keys return 401; missing URL-generation scope returns 403; an inaccessible Source returns 404. For responsive layouts, also scale height, font size and padding for each requested width.
Make it responsive
<img
src="https://imgexo.com/shop/item.jpg?w=800&auto=format,compress"
srcset="https://imgexo.com/shop/item.jpg?w=400&auto=format,compress 400w,
https://imgexo.com/shop/item.jpg?w=800&auto=format,compress 800w"
sizes="(max-width: 600px) 100vw, 800px"
width="800" height="600" alt="Product description"
/>Keep credentials on the backend
Normal image GET requests in compatibility mode do not need an API key. Machine URL generation uses POST /v1/urls with a scoped Bearer key and returns url, srcset and activeRevision. Keep keys server-side and restrict their sources.
Signed-only sources require Imgexo HMAC signatures. Build and cache URLs server-side; you do not need to call the management API for every viewer request.
Understand the cache layers
An eligible edge hit is served by global CDN. On a miss, Imgexo checks the cached original and stored variant before creating a new derivative. Changing content or a published configuration can change the variant identity. Browser caches and an outer proxy cache have their own lifecycles.