Smile simulation API for products that need control

Capabilities

Five operations partners use to build chairside tools, web lead funnels and white-label experiences.

Patient-facing UI

Enterprise API v1 is API-only (server-to-server). There is no hosted or embeddable patient UI for operation, shade or style selection — you build that UI in your product and call the REST API from your backend.

Options & shades

Partners get parameters, not a single black-box knob. Prefer the runtime options catalog (fetched with your key) so enums stay current.

• We only expose shades validated for consistent results. Among them, A1, A2 and B1 are most commonly requested. More shades can ship in a later revision once validated.
• When options change, the catalog updates automatically. Major additions are noted in the partner guide and emailed to active partners.
• Whitening levels and makeover shades are separate — do not merge them into one UI control.

Video

Pass the completed still's job id (with a result URL) or that still's result URL. Video credits are separate from the still-job pool.

Photo guidelines

Good inputs produce reliable outputs.

Technical limits: max 12 MB · short side ≥ ~512 px · long side ≤ ~4096 px · JPEG / PNG / WebP with matching contentType.

How integration works

Async by design. Your base URL and signed examples are delivered with the sandbox key — not published on this page.

1. 1

   Upload

   Request a short-lived upload slot, then PUT the image from your backend.

2. 2

   Create job

   Choose operation and options. Receive a job id immediately.

3. 3

   Poll or webhook

   Poll job status, or register an HTTPS webhook. Download the time-limited result URL when complete.

# 1. Upload photo
UPLOAD=$(curl -sS -X POST "$BASE/uploads" \
  -H "Authorization: Bearer $YOUR_KEY" \
  -d '{"contentType":"image/jpeg"}')
curl -X PUT "$(echo $UPLOAD | jq -r .uploadUrl)" \
  -H "Content-Type: image/jpeg" \
  --data-binary @patient.jpg

# 2. Create job
JOB=$(curl -sS -X POST "$BASE/jobs" \
  -H "Authorization: Bearer $YOUR_KEY" \
  -d '{"operation":"makeover","inputKey":"...","options":{"style":"oval"}}')

# 3. Poll & download
JOB_ID=$(echo $JOB | jq -r .jobId)
while true; do
  STATUS=$(curl -sS -H "Authorization: Bearer $YOUR_KEY" "$BASE/jobs/$JOB_ID")
  [ "$(echo $STATUS | jq -r .status)" = "completed" ] && break
  sleep 3
done
curl -L -o result.png "$(echo $STATUS | jq -r .resultUrl)"

Polling alone is enough to ship an MVP. Webhooks are optional when you're ready.

Webhooks

When you're ready for webhooks, we provide your partner webhook secret. It is separate from the API key and used only to verify webhook POSTs from us (HMAC). Keep it server-side only.

You don't need the secret while polling. Ask when you want webhooks and we'll send it.

Input checks (face preflight)

Before the heavy pipeline runs, uploads are validated for size, dimensions and face presence. Content failures finish as a failed job with a stable error.code so your UI can show a clear retake message.

• File size and pixel-dimension gates
• Face detected and large enough in frame
• Frontal-ish pose heuristics
• Mouth visibility / smile-open checks when applicable

Error codes

Content failures do not return HTTP 400 on job create. The job is accepted, then ends as status: failed. Read error.code from job status or the webhook. HTTP 400 means bad request only (invalid JSON, fields or options).

Results & retention

We process the face photo and generated stills and video for simulation only — not clinical history or chart notes. Data-handling detail: see the privacy policy.

Typical timings

Guidance only — always wait for completed or failed status (or the webhook).

Sandbox, live & BAA

Common questions