Developer guide · AI Studio

Prepare. Review.
Then deliver.

AI processing is an authenticated, asynchronous workflow. Public image URLs only render saved, approved results.

Check availability first

Use the signed-in management API at https://admin.imgexo.com/api/admin/v1. Requests use the current workspace membership and x-workspace-id. Viewers can inspect capabilities; Editors can create jobs and approve results; Admins configure provider access and limits.

GET /ai/capabilities

Check each action’s available flag and setup reason. An unavailable provider produces an explicit setup error. The public playground never triggers paid AI calls.

Remove or replace a background

Use action: "remove-background" to extract a transparent foreground, or action: "replace-background", prompt: "A bright modern office" to generate a new scene and composite the extracted foreground. Replacement keeps the source framing (up to 1536 pixels); choose a source with the full subject in frame. The pinned local model performs foreground extraction; remove.bg is optional. The same workspace AI budget, asynchronous jobs, private previews, approval and retention apply. Public image URLs reuse approved output and never perform fresh background generation.

Create a processing job

POST /sources/{sourceId}/ai/jobs
Idempotency-Key: a-unique-request-id
Content-Type: application/json

{
  "relativePath": "images/portrait.jpg",
  "action": "smart-crop",
  "aspectRatio": 0.8,
  "language": "he"
}

Actions: smart-crop, remove-background, describe, redact, upscale, expand and index. Redaction accepts targets: faces, plates or both. Enhancement accepts upscale: 2 or 4, and denoise. Expansion accepts an aspect ratio, optional prompt and placement: center, left or right. Aspect ratios range from 0.2 to 5. Descriptions support he and en. Use a published source and an original relative image path. A 202 response returns the operation ID.

Generative fill: a new canvas, one saved result

Choose Generative fill & expand in AI Studio. Enable exact canvas dimensions (64–1,536 pixels per axis, aspect ratio 0.2–5), choose the original placement and generate a private preview. The complete original is fitted without cropping or upscaling, then restored over the AI-generated surroundings.

POST /sources/{sourceId}/ai/jobs
{
  "relativePath": "images/portrait.jpg",
  "action": "expand",
  "canvasWidth": 760,
  "canvasHeight": 480,
  "placement": "center"
}

Both canvas dimensions are required for an exact-size request. Review and approve the result. Approval returns fillUrl and fillSrcset in addition to the saved asset URL:

/my-source/images/portrait.jpg?w=760&h=480&fit=fill&fill=gen&fill-id=ai_…&auto=format,compress

fill-id selects the approved expansion tied to this workspace, source revision and original path. A public GET never creates or approves a paid AI operation. Missing approval, expired results, blocked originals and a changed layout are rejected. Generate and approve a new fill for another aspect ratio. Width, height and format variants reuse the saved result; keep the same canvas aspect ratio. Signed sources still require a valid signature. The original source file is preserved.

Explore real prepared examples in the Playground.

Poll and review

GET /jobs/{jobId}
GET /sources/{sourceId}/ai/results/{resultId}
GET /sources/{sourceId}/ai/results/{resultId}/preview

Completed jobs expose result.resultId. Image results include dimensions and expiry. The preview endpoint returns a private data URL. Descriptions include suggested alt and tags. The console shows the original beside the generated image. Detection is subject framing, not identity recognition.

Approve the result

POST /sources/{sourceId}/ai/results/{resultId}/approve

Image approval returns a standard delivery URL and responsive srcset. Its path uses /{sourceSlug}/_ai/{resultId}.png. Width and format parameters use the existing renderer and source signing rules. Unapproved images are unavailable from public delivery. Approval of a description records the editorial review; your publishing system still needs to insert the text.

Create a private video preview

Use the same authenticated job endpoint with action: "image-to-video". Choose motionPreset: zoom-in, zoom-out, pan-left, pan-right or subtle-motion; videoDuration: 4, 6 or 8 seconds; and videoAspectRatio: 16:9 or 9:16. An optional prompt adds motion direction. Output is 720p MP4 without audio. Check the action's availability first; video generation requires separate activation.

Poll the same job. When ready, load GET /sources/{sourceId}/ai/results/{resultId}/video with your authenticated session and workspace header. The private response uses no-store. Watch the full clip, then approve it through the existing approval endpoint. Approval returns /{sourceSlug}/_ai/{resultId}.mp4 for a standard HTML video player. Video URLs serve saved approved files and reject image-transform or motion-generation parameters. Reusing an approved video does not generate it again. A video attempt also consumes the workspace AI limit; the separate video limit defaults to 10 per month. AI may alter faces, products or text.

POST /sources/{sourceId}/ai/index
{ "paths": ["images/photo-1.jpg", "images/photo-2.jpg"] }

POST /ai/search
{ "query": "אישה עם מטרייה אדומה", "sourceId": "optional-source-id" }

GET /ai/library
GET /sources/{sourceId}/ai/known-images

Indexing is an explicit background operation, up to 25 paths per batch and 1,000 indexed images per workspace. Known paths come from previous image requests and connection tests; the service does not crawl remote folders. The index is private to the workspace and excludes blocked, disabled, expired or old-revision assets. Hebrew queries are translated for the visual embedding model. Query analysis is reused for up to 24 hours. Results are ranked by approximate visual similarity, not verified facts.

Limits, retention and retries

The default AI Studio limit is 100 operation attempts per UTC calendar month, shared by editing, indexing and uncached searches. An operation may make more than one provider request. Smart Focus URL detection has its own existing analysis limit. Admins can change the limit or disable AI. Cached result reuse does not consume another provider attempt. Attempts may consume quota even when the provider fails; this counter is an operational limit, not an invoice.

Inputs are sent to the configured provider. Provider processing is not promised to stay in a particular region. Generated images use source retention and are tied to the source configuration revision. Renew an expired result or regenerate it after a source revision change.

Retries never silently repeat a provider call with a known interrupted outcome. Start a new operation explicitly after reviewing the error. Identical completed results can be reused. Source blocking and disabled sources still apply.

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.