Developer guide

Good images.
Straightforward URLs.

The essentials for connecting a source and building your first image URL. No client SDK is required for image delivery.

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,compress

The 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&amp;auto=format,compress"
  srcset="https://imgexo.com/shop/item.jpg?w=400&amp;auto=format,compress 400w,
          https://imgexo.com/shop/item.jpg?w=800&amp;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.

Big on images.
Light on everything else.

Let’s build a simpler image pipeline for your next million requests.

Enterprise image optimization. Built for scale.