Developer documentation

Retouch AI REST API

Everything in the studio is this API. Sign up for a free key, POST a photo, download the result — no demo call, no contract, no SDK required. Credits are reserved when a job is created and automatically refunded if the job fails, so a crash can never cost you money.

Authentication

Every request carries your key in the Authorization header. Keys start with rtai_ and are shown once at creation — we store only a hash.

Authorization: Bearer rtai_<your key>

Endpoints

POST/api/retouch-ai/signup

Create an account: { "email": "you@studio.com" }. Returns your API key (once) and a free-tier credit grant. Rate-limited per IP.

GET/api/retouch-ai/ops

The live operation catalog: key, label, price in credits, availability. 1 credit = $0.01. Public — no auth needed.

POST/api/retouch-ai/jobs

Create a job. Body: { "ops": ["auto_correct","look_warm"], "contentType": "image/jpeg", "contentLength": 1234567, "params": { ... } }

Rules: 1–3 operations per job; at most one GPU-class operation; video / reel / eraser / 3D / generate / quality-score run alone. Credits are reserved atomically — the response includes creditsCharged and a presigned upload URL (PUT your bytes straight to storage; they never pass through our web servers). Reel jobs return one presigned URL per photo (assetCount 3–20); Magic Eraser returns a second URL for the painted mask; text-to-image jobs skip upload entirely.

Common params: style (ai_portrait / ai_art), background (replacement preset or #hex), prompt (ai_edit / generate — content-screened before any charge), skin/eyes/teeth/catchlights/contour/lips (face retouch strengths 0–100), template/format/title (reels), format: "stl" (3D print export).

POST/api/retouch-ai/jobs/{id}/process

Run the job after your upload completes. Synchronous — returns when done.

GET/api/retouch-ai/jobs/{id}

Status + signed resultUrl (1h TTL) when succeeded. Extras where earned: resultUrls (reel pack: 9x16 / 1x1 / 16x9), stlUrl (print-ready 3D export), scene + sceneLabel (the content-aware verdict the grade used), error with automatic refund on failure.

POST/api/retouch-ai/preview

Free live preview: POST downscaled JPEG bytes (≤4MB) with slider params or ?effect=<preset>&w=<px>. Identical math to the paid render — what you preview is exactly what you buy.

POST/api/retouch-ai/billing/topup

Body { "pack": "starter" | "pro" | "volume" } → Stripe Checkout URL. Bigger packs carry bonus credits.

GET/api/retouch-ai/ledger

Your full credit history: charges, refunds, top-ups, grants.

GET/api/retouch-ai/keys

List keys; POST mints a new one (max 5 active), DELETE revokes — the last active key cannot be revoked.

Complete example

# 1. Sign up (once) — save the key, it is shown only once
curl -s -X POST https://www.fotiqo.com/api/retouch-ai/signup \
  -H "Content-Type: application/json" -d '{"email":"you@studio.com"}'

# 2. Create a job
curl -s -X POST https://www.fotiqo.com/api/retouch-ai/jobs \
  -H "Authorization: Bearer rtai_..." -H "Content-Type: application/json" \
  -d '{"ops":["auto_correct"],"contentType":"image/jpeg","contentLength":2048000}'
# → { "jobId": "...", "upload": { "url": "..." }, ... }

# 3. Upload the photo bytes directly to storage
curl -s -X PUT "<upload.url>" -H "Content-Type: image/jpeg" --data-binary @photo.jpg

# 4. Process
curl -s -X POST https://www.fotiqo.com/api/retouch-ai/jobs/<jobId>/process \
  -H "Authorization: Bearer rtai_..."

# 5. Download
curl -s https://www.fotiqo.com/api/retouch-ai/jobs/<jobId> \
  -H "Authorization: Bearer rtai_..."
# → { "status": "succeeded", "resultUrl": "https://...", "scene": "SUNSET", ... }

Batch automation

Whole-shoot automation is one loop: watch a folder, create a job per new file, PUT the bytes, process, download. The API allows 120 job creations per minute per account — comfortably above a tethered camera's pace, so a hot-folder watcher keeps up with a live shoot in real time.

Start free

Free credits at signup — enough to test every operation before spending a cent.

Get your API key