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 / style selection. You build that UI in your product and call the REST API from your backend.

A white-label / embeddable UI would be a separate product — not part of this integration.

Options & shades

Partners get parameters — not a single black-box “beautify” knob. Prefer the runtime options catalog (with your key) so enums stay current; you may hard-code the table below as a fallback.

• 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 / changelog and emailed to active partners.
• Whitening levels and makeover shades are separate — don’t 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

Same idea as clinical smile-simulators: good inputs produce reliable outputs.

How integration works

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

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

# 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)" --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)"
echo "Saved result.png  |  refineToken: $(echo $STATUS | jq -r .refineToken)"

Webhooks

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

You don’t need the secret while polling. Start with your sandbox key; ask when you want webhooks and we’ll send the secret.

Input checks (face preflight)

Before makeover, whitening, or align run the heavy pipeline, we validate size, dimensions, and face presence. Content failures finish as a failed job with a stable error.code — so your product UI can show a clear “retake photo” 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

Shade and video skip raw-upload preflight (they continue from a completed still you already own).

Error codes (short)

Content failures do not return HTTP 400 on job create. The job is accepted, then ends as status: failed. Read error.code / error.message from job status (or the webhook).

HTTP 400 = bad request only (invalid JSON / fields / options). Branch your UX on the code; treat unknown codes like a generic processing failure.

Results & retention

No self-service delete in v1 yet. Deletion under agreement / BAA is available on request; a partner purge API is on the roadmap.

We process the face/smile photo (and generated stills/video) for simulation only — not clinical history or chart notes.

Typical timings

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

Sandbox, live & BAA

Sandbox can continue on test images while the BAA / order form are in review. Share expected monthly volume (makeover / align / whitening / shade / video) so we can recommend a plan.

Common questions

© SmileCraft AI · Alborz Solutions LLC · Home · Claude · smilecraft.app