Pixelift

Pixelift API · v1

One upscaling backend, many storefronts

All requests except session creation carry X-Pixelift-Session: <token>. Every response is JSON; errors are { error: { code, message } }. Ownership is checked on every request — an asset from another session or client returns 404.

Endpoints

POST/api/v1/sessionsStart a session. Body {client_id}. Guest clients: Origin must be allow-listed. server_key clients: Authorization: Bearer <client key>. Returns {session_id, token, expires_at}.
POST/api/v1/uploadsmultipart: file (JPEG/PNG/WebP ≤10 MB), profile (photo|artwork). Returns asset with original dimensions.
GET/api/v1/print-configSession required. Returns enabled print standards and current factor/output limits.
POST/api/v1/assessBody {asset_id, print_width_cm, print_height_cm, preset_id?, border_cm?, mode: fit|fill, crop_approved?}. Returns original/print dimensions, raw effective PPI, size-specific thresholds, classification, recommended factor, optional estimated custom standards and actual enhanced PPI. Fill requires approval; Fit evaluates the fitted image area.
POST/api/v1/upscaleHeader Idempotency-Key. Body {asset_id, factor: 2|4}. Enforces limits, starts a Topaz job (High Fidelity V3 or Wonder 3.5, from the saved enhancement mode). Returns job.
GET/api/v1/jobs/{jobId}Job status; polls provider, verifies output dimensions on completion.
POST/api/v1/jobs/{jobId}/cancelCancel a running job.
GET/api/v1/assets/{assetId}Asset with dimensions and 10-minute signed view URLs.
DELETE/api/v1/assets/{assetId}Delete original and enhanced files immediately.
POST/api/v1/assets/{assetId}/approveRecord customer approval of the enhanced image.
POST/api/v1/assets/{assetId}/downloadBody {variant: enhanced|original}. Enhanced requires approval. Returns 5-minute signed URL.

Responses include job ID, asset ID, status, original/enhanced dimensions, effective PPI, errors and download availability. Provider webhook: POST /api/public/v1/replicate-webhook (signature-verified).

Integration clients

  • pixelift — standalone app, guest sessions from its own origin.
  • myartlane — server_key policy. The Shopify app proxy / backend creates sessions with its client key and hands the token to the widget.
  • artside — server_key policy. ArtSide's backend verifies its own user, creates a session with owner_ref = ArtSide user id, and passes the token to the Studio component.
  • Each client has its own allowed origins, limits, feature flags and credit-integration reference, configured in the admin dashboard.

MyArtLane Shopify specification (Phase 2 — not live)

  • Add an “Enhance Your Photo” link on the Envy product page, alongside — never replacing — the Gelato Personalize button.
  • The link opens the embeddable Pixelift widget (the same React upscaler, client myartlane).
  • Flow: upload → assess → optional upscale → approve → download → return to product → upload the enhanced file in Gelato Personalization Studio as usual.
  • Optional return_url is validated against MyArtLane's allowed origins before showing “Back to product”.
  • No changes to Gelato Studio, product mappings, variants or checkout.

ArtSide.ai specification (Phase 3 — not live)

  • AI Upscaler tool in ArtSide Studio: upload or pick from gallery, Photo/Artwork Fidelity, 2×/4×, preview and download.
  • Gallery selection: ArtSide's backend fetches the image and posts it to /api/v1/uploads server-side.
  • Credits: credit_integration = artside_credits is reserved. Phase 1 deducts nothing; a future pre-upscale hook will reserve credits and refund failed jobs.
  • Print preparation: on “Order Physical Print”, call assess; offer upscale if not green; show the result for approval; download; direct to MyArtLane. Never regenerate the artwork.

Security & testing checklist

  • Replicate credentials are server-only; no API keys in the browser.
  • Private buckets only; signed URLs expire (view 10 min, download 5 min, provider 60 min).
  • Signed HMAC session tokens; client server keys stored as SHA-256 hashes.
  • Limits enforced server-side before Replicate: 3 successful upscales / session / 24 h, 1 active job, daily spend cap, max output size, 10 MB input, session-creation rate limit, idempotency keys.
  • Failed jobs are never counted as usage; results are only “succeeded” after the actual output is downloaded and its dimensions verified.
  • Retention cleanup runs hourly; customers can delete their images at any time.
  • Automated tests: upload validation, PPI maths, 2×/4× selection, aspect ratio, provider failure, output verification, limits, ownership, signed token expiry, download metadata, client isolation, cleanup selection.
  • Manual tests: low-res portraits, landscapes, family photos, pencil sketches, oil paintings, AI images, already print-ready images.