Quick start

# One call: upload, adjust, download. Output is JPEG, EXIF stripped.
curl -X POST https://retouchengine.com/v1/edit \
  -H "X-API-Key: rte_..." \
  -F "image=@photo.jpg" \
  -F 'ops=[{"op":"autotone"},{"op":"clarity","amount":0.5}]' \
  -o edited.jpg

Response headers tell you exactly what happened: X-Ops-Applied (the applied chain), X-Elapsed-Ms, X-Output-Size, X-Key-Usage (today's usage / your daily limit).

Authentication

Send your key in the X-API-Key header. Create a profile to get a trial key instantly (25 requests/day): upgrade any time on Pricing. Missing/invalid key → 401 · over daily limit → 429 (resets midnight UTC).

The edit call

POST /v1/edit, multipart form: image (JPEG/PNG/WebP, ≤ 40 MB, ≤ 40 MP), ops (JSON list, up to 20 operations, applied in order), optional preset (runs before ops), quality (50–100, default 92) and max_edge (downscale the long edge, e.g. 2000 for web delivery). Nothing is ever stored on our servers.

Operations

Tone

Color

Detail

Geometry

Finish

Branding

People

Cutout

Presets

Named recipes, run alone or as a starting point before your own ops.

Read with AI

AI for inspection, old school code for retouch. The model looks at your photo and a style brief, then recommends concrete catalog settings. It never touches a pixel: the recommendation is a plain ops chain, and the edit that runs it is fully deterministic. Note the honest split, the recommendation may vary between calls (it is advice); the edit of a given chain never does.

# Get a recommendation (JSON chain you can inspect, store, replay)
curl -X POST https://retouchengine.com/v1/analyze -H "X-API-Key: rte_..."   -F "image=@photo.jpg"   -F "prompt=candid style editing with a bit of glamour"

# Or apply it in the same call and get the finished JPEG
curl -X POST https://retouchengine.com/v1/analyze -H "X-API-Key: rte_..."   -F "image=@photo.jpg" -F "prompt=warm editorial look"   -F "apply=true" -o edited.jpg
# X-Ops-Applied shows exactly which deterministic chain ran

Your presets

Save your own named chains and use them exactly like built-in presets.

# Save (or replace) a preset, chains may include your custom ops
curl -X POST https://retouchengine.com/v1/presets -H "X-API-Key: rte_..."   -H "Content-Type: application/json"   -d '{"name":"my_look","chain":[{"op":"autotone"},{"op":"warmth","amount":0.2}]}'

# Use it
curl -X POST https://retouchengine.com/v1/edit -H "X-API-Key: rte_..."   -F "image=@photo.jpg" -F "preset=my_look" -o edited.jpg

GET /v1/presets lists yours · DELETE /v1/presets/<name> removes one. Your presets shadow built-ins with the same name.

Custom operations (AI-written, human-owned)

Need something the catalog doesn't have, say, highlight beards? Describe it and the engine's AI writes the operation as code you can read. Every version is stored, inspectable and callable forever, and the code passes three gates before it can ever run: a static allow-list (only numpy/cv2/math, no file or network access, no reflection), a resource-capped sandbox process, and a determinism check, the op must produce byte-identical output on repeated runs.

# 1. Create an operation from natural language
curl -X POST https://retouchengine.com/v1/custom-ops -H "X-API-Key: rte_..."   -H "Content-Type: application/json"   -d '{"name":"beard_glow","request":"gently brighten beard areas on faces"}'

# 2. Use it in any chain (v optional, defaults to latest)
curl -X POST https://retouchengine.com/v1/edit -H "X-API-Key: rte_..."   -F "image=@photo.jpg"   -F 'ops=[{"op":"autotone"},{"op":"custom:beard_glow","strength":0.5}]' -o out.jpg

# 3. Iterate, every request becomes a NEW version; old ones stay callable
curl -X POST https://retouchengine.com/v1/custom-ops/beard_glow/versions   -H "X-API-Key: rte_..." -H "Content-Type: application/json"   -d '{"request":"softer edges and a touch stronger"}'
# pin an old version in a chain: {"op":"custom:beard_glow","v":1}

Custom ops receive ctx["person_alpha"] (a person mask) and ctx["face_boxes"] (face rectangles) so they can target people and faces - deterministically, never generatively. GET /v1/custom-ops lists yours with all versions; GET /v1/custom-ops/<name>/code returns the code itself. Codegen has its own daily allowance (trial 5 · starter 25 · pro 100).

Machine-readable

GET /v1/ops returns this whole catalog as JSON (params, ranges, defaults, presets, limits) - build UIs against it. OpenAPI schema at /openapi.json, interactive explorer at /api-explorer.

Errors