A SMALL API FOR BIGGER TRUST

Meet your toolkit.

Photo checks, text moderation and a short-video beta. One API key. Add useful safety signals to the experience you’re building.

Your first request

Ask your service administrator for an account and credits, then generate a key from your dashboard. Keep this key on your server; never embed it in a mobile app or public browser code.

curl https://api.emeraldtrustengine.com/v1/analyze-face \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: photo-123-face-v1' \
  -d '{"imageBase64":"BASE64_ENCODED_IMAGE"}'

Send raw base64, without a data:image/… prefix. JPEG, PNG and WebP are supported. Use a different idempotency key for every distinct analysis.

Shared response format

All public /v1/ analysis responses share ok, operation, status, requestId, creditsCharged and error. Moderation tools include moderation and scores. AI-image detection returns its confidence percentage; profile-photo classification returns category match percentages without moderation decisions. Endpoint-specific fields remain at the top level for compatibility. Authentication, validation, capacity and worker errors use the same format. Browser account/admin/billing APIs have their own resource formats.

status is completed or failed; video jobs also use queued and processing. ok: true means accepted or successfully analyzed, not that the content is allowed. Wait for a completed result before acting. The X-Request-Id header matches requestId.

For endpoints that return moderation decisions, use moderation.decision: allow, review, reject, inconclusive, unavailable, pending or not_applicable. moderation.reviewRequired is true for review, inconclusive and unavailable results. Reasons are machine-readable strings when the endpoint supplies them. Face detection, face comparison and OCR return not_applicable; they do not make content moderation decisions. For age safety, legacy clear maps to inconclusive, since estimated ages cannot verify adulthood.

scores contains named 0–1 model signals: faceDetection, faceSimilarity, nudity/explicitNudity/reviewNudity, text categories, or legacy nudity detection labels. AI-image detection returns its one percentage as confidence and omits scores and moderation. Profile-photo classification uses 0–100 category scores and omits moderation. Higher values indicate a stronger signal for that name; they are not calibrated probabilities of correctness. No aggregate confidence is invented: scores are empty for age estimates, OCR, video and fallback photo results without numeric signals. OCR confidence remains in each lines[].confidence; video evidence uses evidence[].score. Other endpoints retain their original score fields.

error is null on success and a machine-readable string on failure, with a detail message when available. Failed analysis never becomes allow or reject. Completed idempotent replays preserve the recorded policy outcome; changing a threshold requires a new idempotency key. Older stored responses gain the common structure when replayed. The AI-image percentage-only contract is described below.

The interactive OpenAPI documentation and JSON schema include response schemas and examples for every analysis endpoint.

Try before integrating

In the customer playground, choose a tool from the dropdown. Photo tools show an upload area; choosing Text moderation (beta) replaces it with an English text field and content-type controls. Run analysis to see the result and export its JSON. Text checks share the text beta’s 200-attempt daily account limit and spend no purchased credits. Photo checks use a separate allowance of 200 evaluation checks per customer over 14 days, with optional labels and three-trial timings. Submitted photos and native text are discarded after processing. Limited zero-credit activity and outcome summaries appear in Usage for up to 30 days. Nudity screening uses fallback processing only if primary analysis fails; that may send photos to an external provider. An unavailable analysis never means allow.

Video nudity moderation

BETA · FREE
POST /v1/moderate-video

Upload one MP4 or WebM clip as multipart form field file. Use your server-side API key and a unique Idempotency-Key. The accepted response is HTTP 202 with a jobId and relative statusUrl. Poll GET /v1/moderate-video/{jobId} with the same account's API key until status is completed or failed. A failed job is unavailable, never approved. The signed-in video playground uses the same queue.

curl https://api.emeraldtrustengine.com/v1/moderate-video \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: clip-123-beta-v1' \
  -F 'file=@clip.mp4'
# Poll the statusUrl returned by the upload:
curl https://api.emeraldtrustengine.com/v1/moderate-video/JOB_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'

Limits: 20 MiB upload, 60 seconds, one video stream, up to 3840 × 2160 pixels, and 20 submissions per customer per UTC day across API and playground. H.264/H.265 MP4 and VP8/VP9/AV1 WebM are supported in the beta. Processing samples roughly two frames per second and up to 32 scene changes, with at most 152 frames. The result contains decision (allow, review, or reject), scope: sampled_frames, framesAnalyzed, and up to ten flagged evidence timestamps in milliseconds. Two flagged explicit frames reject; one routes to review. Your API settings' two-outcome mode maps review to reject. Unchecked moments can be missed; no whole-video safety guarantee is made.

Accepted response · HTTP 202

{
  "creditsCharged": 0,
  "error": null,
  "jobId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "moderation": {
    "decision": "pending",
    "reasons": [],
    "reviewRequired": false
  },
  "ok": true,
  "operation": "moderate-video",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "scores": {},
  "status": "queued",
  "statusUrl": "/v1/moderate-video/d2893b02-37a9-428f-84ed-283589cf784b"
}

Completed polling response · HTTP 200

{
  "created": 1794000000,
  "creditsCharged": 0,
  "decision": "review",
  "durationMs": 5000,
  "error": null,
  "evidence": [
    {
      "atMs": 1500,
      "decision": "reject",
      "score": 0.98
    }
  ],
  "framesAnalyzed": 10,
  "jobId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "moderation": {
    "decision": "review",
    "reasons": [
      "possible_explicit_nudity_in_one_frame"
    ],
    "reviewRequired": true
  },
  "ok": true,
  "operation": "moderate-video",
  "policyVersion": "dating-photo-v1",
  "reasons": [
    "possible_explicit_nudity_in_one_frame"
  ],
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "result": {
    "creditsCharged": 0,
    "decision": "review",
    "durationMs": 5000,
    "error": null,
    "evidence": [
      {
        "atMs": 1500,
        "decision": "reject",
        "score": 0.98
      }
    ],
    "framesAnalyzed": 10,
    "moderation": {
      "decision": "review",
      "reasons": [
        "possible_explicit_nudity_in_one_frame"
      ],
      "reviewRequired": true
    },
    "ok": true,
    "operation": "moderate-video",
    "policyVersion": "dating-photo-v1",
    "reasons": [
      "possible_explicit_nudity_in_one_frame"
    ],
    "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
    "sampling": {
      "regularFrames": 10,
      "regularIntervalMs": 500,
      "sceneFrames": 0
    },
    "scope": "sampled_frames",
    "scores": {},
    "status": "completed"
  },
  "sampling": {
    "regularFrames": 10,
    "regularIntervalMs": 500,
    "sceneFrames": 0
  },
  "scope": "sampled_frames",
  "scores": {},
  "status": "completed"
}

Failed polling response · HTTP 200

{
  "created": 1794000000,
  "creditsCharged": 0,
  "error": "processing_unavailable",
  "jobId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "moderation": {
    "decision": "unavailable",
    "reasons": [
      "processing_unavailable"
    ],
    "reviewRequired": true
  },
  "ok": false,
  "operation": "moderate-video",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "result": {
    "creditsCharged": 0,
    "error": "processing_unavailable",
    "moderation": {
      "decision": "unavailable",
      "reasons": [
        "processing_unavailable"
      ],
      "reviewRequired": true
    },
    "ok": false,
    "operation": "moderate-video",
    "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
    "scores": {},
    "status": "failed"
  },
  "scores": {},
  "status": "failed"
}

Failed jobs use HTTP 200 on polling because fetching the job succeeded; ok: false, status: failed and moderation.decision: unavailable describe the failed analysis. Queued and processing jobs return HTTP 202. The nested result remains available for existing integrations.

Raw uploads and extracted frames are deleted after processing. Results and request IPs follow the 30-day retention policy. Replaying an idempotency key for the same file returns the original job; using it for a different file returns HTTP 409. Video beta checks cost zero paid credits.

Face detection

1 CREDITS / SUCCESS
POST /v1/analyze-face
{"imageBase64":"…","filename":"profile.jpg","minConfidence":0.5}

Returns faceDetected, faceCount, and confidence.

Example response · HTTP 200

{
  "confidence": 0.9876,
  "creditsCharged": 1,
  "elapsedMs": 125.4,
  "error": null,
  "faceCount": 1,
  "faceDetected": true,
  "moderation": {
    "decision": "not_applicable",
    "reasons": [],
    "reviewRequired": false
  },
  "ok": true,
  "operation": "analyze-face",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "scores": {
    "faceDetection": 0.9876
  },
  "status": "completed"
}

Face comparison

5 CREDITS / SUCCESS
POST /v1/compare-faces

Compare a selfie with up to six profile images. This is a similarity signal to support a verification flow, not a guarantee of identity.

{"selfieBase64":"…","profilePhotosBase64":["…","…"]}

Returns facesMatch, similarity, distance, and comparedCount.

Example response · HTTP 200

{
  "comparedCount": 2,
  "creditsCharged": 5,
  "distance": 0.28,
  "elapsedMs": 125.4,
  "error": null,
  "facesMatch": true,
  "moderation": {
    "decision": "not_applicable",
    "reasons": [],
    "reviewRequired": false
  },
  "ok": true,
  "operation": "compare-faces",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "scores": {
    "faceSimilarity": 0.72
  },
  "similarity": 0.72,
  "status": "completed"
}

Nudity detection

2 CREDITS / SUCCESS
POST /v1/analyze-nudity
{"imageBase64":"…","filename":"profile.jpg"}

Legacy nudity screening endpoint. Its category mapping remains unchanged for existing integrations; use moderate-photo for the shared playground policy. Returns nudityDetected, explicitNudityDetected, reviewRequired, detections, and moderationStatus (approved, pending_review, or rejected). In the playground, explicit and review categories use the shared allow/review/reject policy at the selected threshold; that score is not a calibrated whole-image probability.

Example response · HTTP 200

{
  "creditsCharged": 2,
  "detections": [
    {
      "box": [
        10,
        20,
        100,
        150
      ],
      "label": "BUTTOCKS_EXPOSED",
      "score": 0.82
    }
  ],
  "elapsedMs": 125.4,
  "error": null,
  "explicitNudityDetected": false,
  "moderation": {
    "decision": "review",
    "reasons": [],
    "reviewRequired": true
  },
  "moderationStatus": "pending_review",
  "nudityDetected": true,
  "ok": true,
  "operation": "analyze-nudity",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "reviewRequired": true,
  "scores": {
    "BUTTOCKS_EXPOSED": 0.82
  },
  "status": "completed"
}

Age safety

3 CREDITS / SUCCESS
POST /v1/analyze-minor-safety
{"imageBase64":"…","filename":"profile.jpg"}

Returns decision (clear, pending_review, or rejected) and estimates with estimated ages. Estimates at or below 12 route to rejection; estimates below 18 route to review. A clear result is not proof of adulthood. Use appropriate age assurance and human review in your own product.

Example response · HTTP 200

{
  "creditsCharged": 3,
  "decision": "pending_review",
  "elapsedMs": 125.4,
  "error": null,
  "estimates": [
    {
      "estimatedAge": 16.4,
      "index": 0,
      "source": "face"
    }
  ],
  "moderation": {
    "decision": "review",
    "reasons": [],
    "reviewRequired": true
  },
  "ok": true,
  "operation": "analyze-minor-safety",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "scores": {},
  "status": "completed"
}

Photo text detection

2 CREDITS / SUCCESS
POST /v1/analyze-text
{"imageBase64":"…","filename":"profile.jpg"}

Defaults to variant: "small" and threshold: 0.8. Choose "tiny" for lower latency; The balanced mode is better suited to difficult text. Optional recognition threshold: 0.1–0.99.

{"imageBase64":"…","variant":"small","threshold":0.8}

Returns textDetected, rawText, phoneNumbersDetected, phoneNumberDetected, lines with recognition confidence, threshold and timings. Phone numbers are candidates; validate them for your region. False positives and missed text remain possible. Images are processed in memory. Existing idempotency keys retain their original result, including results generated before analysis updates; use a new key to rerun.

Example response · HTTP 200

{
  "creditsCharged": 2,
  "elapsedMs": 125.4,
  "error": null,
  "lines": [
    {
      "confidence": 0.96,
      "text": "Hello world"
    }
  ],
  "moderation": {
    "decision": "not_applicable",
    "reasons": [],
    "reviewRequired": false
  },
  "ok": true,
  "operation": "analyze-text",
  "phoneNumberDetected": false,
  "phoneNumbersDetected": [],
  "rawText": "Hello world",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "scores": {},
  "status": "completed",
  "textDetected": true,
  "threshold": 0.8
}

Photo moderation

1 CREDITS / SUCCESS
POST /v1/moderate-photo
{"imageBase64":"…","filename":"profile.jpg"}

One successful photo moderation uses one check. The default three-outcome mode returns decision as allow, review or reject. In API settings, customers can choose two-outcome mode (allow/reject); every review signal then becomes reject, never allow. Responses include decisionMode, thresholdSource, reasons, policyVersion, checksCharged and timings. The account default screening threshold is 0.45 until changed in API settings, where it is bounded to 0.25–0.75. A per-request threshold (0.25–0.99) overrides that default for the request. Lower thresholds flag more photos; higher thresholds may miss sensitive content. The threshold applies only to primary screening. Scores are detector signals, not whole-image safety probabilities.

{"imageBase64":"…","threshold":0.45}

The initial policy rejects detected exposed genitalia, anus or breasts above the threshold; other supported exposure signals route to review. Medical/artistic contexts may require a human override. Unknown or undetected content can be missed. A service error is unavailable, never allow; keep the upload pending. External fallback is off by default and requires approved terms and account authorization. Fallback flags route to review in three-outcome mode and reject in two-outcome mode. Errors and unavailable analyses never become allow. Completed idempotent replays return the original decision even if account settings have since changed.

Integration and migration example

Example response · HTTP 200

{
  "checksCharged": 1,
  "creditsCharged": 1,
  "decision": "reject",
  "decisionMode": "three_way",
  "elapsedMs": 125.4,
  "error": null,
  "explicitScore": 0.98,
  "moderation": {
    "decision": "reject",
    "reasons": [
      "explicit_nudity"
    ],
    "reviewRequired": false
  },
  "ok": true,
  "operation": "moderate-photo",
  "policyVersion": "dating-photo-v1",
  "reasons": [
    "explicit_nudity"
  ],
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "reviewScore": 0.12,
  "score": 0.98,
  "scores": {
    "explicitNudity": 0.98,
    "nudity": 0.98,
    "reviewNudity": 0.12
  },
  "status": "completed",
  "threshold": 0.45,
  "thresholdSource": "account"
}

Text moderation (beta)

BETA · FREE
POST /v1/moderate-text

Moderate native text in English dating profiles, usernames and messages. This is separate from analyze-text, which reads text in images. Try it in the playground by selecting Text moderation (beta) from the Tool dropdown; the signed-in playground uses a session, while this API endpoint requires a server-side API key. The beta returns allow or review; it never automatically rejects text or bans an account. Start in shadow mode or human-review routing. No flagged signal is proof of fraud, age or illegal content.

curl https://api.emeraldtrustengine.com/v1/moderate-text \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: message-123-beta-v2' \
  -d '{"text":"Would you like to meet for coffee?","language":"en","context":"message"}'

Optional context: profile (default), message, or username. For local-format phone numbers, pass a per-request ISO two-letter country hint from the sender’s known country; otherCountry can add the other person’s country. Both are optional and support phone regions worldwide. There is no app-wide default. If neither is known, internationally prefixed numbers can still be recognized, but local-format numbers may be missed. Country hints do not change the English-only language scope or prove where a person lives. Never infer a user’s country from the phone number alone.

Returns beta, decision, reasons, policyVersion: dating-text-beta-v2, scores, signals, coverage, reviewRequired, automaticRejection: false, timings and the usual request ID. Scores cover toxicity, severe toxicity, profanity, hate, harassment, threats and sexual content. They are classifier signals, not calibrated probabilities or a complete safety assessment.

Signals cover email/phone candidates, links, possible payment/sexual solicitation, selected underage/self-harm references and limited language coverage. Profiles/usernames route contact details and links to review. Messages allow contact sharing and links alone; set boolean blockContactDetails or blockLinks to override those defaults. Links are never fetched and no link-reputation claim is made. Financial or self-harm flags need human context; this is not a fraud classifier or emergency service.

Free beta limits: 200 attempts per customer per UTC day across the API and playground (including invalid requests and replays), existing 60/minute API limits, one text inference globally, 32 KiB JSON, 4,000 characters and 384 tokens including special tokens. Inputs over the token limit are rejected rather than silently truncated. Successful beta requests charge zero paid checks. On a temporary HTTP 429/503, keep the text pending and retry with the same idempotency key after Retry-After when provided. The daily attempt limit cannot be bypassed by retrying.

Text is processed locally with no external fallback. Submitted text and matched addresses/numbers are never returned or stored; generic results are retained for 30 days for replay, with the existing encrypted backup retention. Validation errors omit submitted values. Quoted abuse, negation, dialects and obfuscation can cause false flags or misses. Language coverage warnings are partial; English is caller-declared. Beta policy and limits may change with notice before a stable contract.

Example response · HTTP 200

{
  "automaticRejection": false,
  "beta": true,
  "context": "message",
  "coverage": "declared_english",
  "creditsCharged": 0,
  "decision": "allow",
  "elapsedMs": 125.4,
  "error": null,
  "language": "en",
  "moderation": {
    "decision": "allow",
    "reasons": [],
    "reviewRequired": false
  },
  "ok": true,
  "operation": "moderate-text",
  "policyVersion": "dating-text-beta-v2",
  "reasons": [],
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "reviewRequired": false,
  "scores": {
    "harassment": 0.003,
    "hate": 0.001,
    "profanity": 0.002,
    "severeToxicity": 0.001,
    "sexual": 0.002,
    "threats": 0.001,
    "toxicity": 0.01
  },
  "signals": {
    "email": false,
    "link": false,
    "paymentSolicitation": false,
    "phone": false,
    "selfHarmReference": false,
    "sexualSolicitation": false,
    "underageReference": false,
    "unsupportedScript": false
  },
  "status": "completed",
  "tokenCount": 12
}

AI-generated image detection

FREE
POST /v1/detect-ai-image

Detection of AI-generated images. Send a JPEG, PNG or WebP image using {"imageBase64":"…"}. Every successful response includes one confidence percentage from 0 to 100. For example, "confidence": 77.45 means 77.45%. The JSON value is numeric, so clients can compare it directly against percentage thresholds. Higher means a stronger AI-generation signal; this is model confidence, not a calibrated probability of correctness. Errors do not return confidence.

Interpret the percentage

90% or higher means most likely AI-generated. Lower scores do not establish that an image is authentic. The endpoint returns the percentage and request metadata only: no review suggestions, rejection decisions, assessments or policy thresholds. Your application decides what action to take. Confidence retains model precision; format it to two decimal places for display.

{"imageBase64":"…"}
// After POST /v1/detect-ai-image:
if (response.ok && response.status === "completed") {
  showConfidence(`${response.confidence.toFixed(2)}%`);
  // response.confidence >= 90 means most likely AI-generated.
}
// response.confidence: 77.45 → "77.45%"

Older stored results also return percentage-only analysis fields when replayed. Previous policy options are accepted for compatibility but ignored; omit them from new requests. Edited photos, screenshots and new generators may be missed or wrongly flagged. Model confidence is not proof of origin or a calibrated probability of correctness.

AI-generated image detection runs locally, costs zero paid credits, and is limited to 100 API attempts per customer per rolling 24 hours. It has no external fallback. Playground trials use the existing photo evaluation allowance. Files may be up to 12 MiB; high-resolution JPEG photos are downsampled before analysis, up to 120 megapixels. PNG and WebP inputs are limited to 20 megapixels; no side may exceed 16,000 pixels. Images beyond those limits return a size error rather than a screening result. As with other image endpoints, use a server-side API key and a unique Idempotency-Key for each distinct request.

Example response · HTTP 200

{
  "confidence": 77.45,
  "creditsCharged": 0,
  "elapsedMs": 125.4,
  "error": null,
  "ok": true,
  "operation": "detect-ai-image",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "status": "completed"
}

Profile photo classification

FREE
POST /v1/profile-photo

Classify profile uploads into personal_photo, clothing_merchandise, footwear_merchandise, product, animal, cartoon, meme, poster, screenshot or landscape_or_object. This includes clothes and shoes displayed for sale, catalogue images and commercial product collections.

{"imageBase64":"BASE64_ENCODED_IMAGE","filename":"profile.webp"}

The response includes faceDetected, faceCount and isProfilePhoto, aiGeneratedConfidence (AI-generation confidence from 0–100), nudity (local screening result), ageEstimates, possibleMinor, textDetected, rawText, contactDataDetected and contactSignals, alongside category (the highest-scoring category), confidence (that category's percentage match), scores (every category's percentage from 0–100), policyVersion and timing. The independent scores do not sum to 100 and are not calibrated probabilities of suitability. The classification returns no review/reject status. isProfilePhoto is true only when category is personal_photo and at least one face is detected and nudity.passed is true. A personal category by itself does not guarantee a face. Recognized text above the fixed 80% OCR recognition threshold is returned in rawText. contactSignals reports phone, email, link and socialHandle candidates; contactDataDetected is true when any is detected. Phone candidates contain 9–15 digits on a single recognized line; physical addresses and QR codes are not decoded. OCR errors, low-confidence or small text, obfuscation and unsupported handle formats can cause misses or false flags. These are contact candidates, not verified contact details. aiGeneratedConfidence is a separate signal from the existing local AI-image detector: 90% or higher means most likely AI-generated; a lower score does not establish authenticity. It does not affect isProfilePhoto, which combines category, face detection and the nudity check. Face detection uses a fixed 50% internal detector threshold; the public confidence remains the category match percentage. faceCount is the count in the successful detection view and may undercount people. Your application chooses its acceptance rules. A low-confidence top match may be unreliable; measure false rejections on representative acceptable photos before enabling blocking.

Local image classification does not establish ownership, identity, or that a photographed person is the uploader. The endpoint combines separate local models for classification, face detection, AI-generation scoring, nudity screening, age estimation and image-text recognition. Faces in posters, cartoons or screenshots do not make those categories qualify as a profile photo. Age estimates are predictions for detected faces or unmatched bodies, not verified ages or identification of the uploader. possibleMinor is true when any estimate is below 18, false when estimates exist and none is below 18, and null when no age estimate is available. Age and contact flags do not change isProfilePhoto; your app chooses how to act on them. No agent or external image-processing API is used.

Successful checks cost zero paid credits and allow 100 attempts per account per 24-hour window, alongside the normal 60/minute limits. Authentication, request IDs and idempotency work as on other image endpoints. Replays return the recorded completed result; use a new key for a new analysis. Inputs support the same 12 MiB, single-frame JPEG/PNG/WebP limits as the AI-image detector, including decoder downsampling of JPEGs up to 120 megapixels. The existing local face detector checks a bounded normalized image, with up to five additional crop views when a personal-photo candidate has no full-image face detection. Every new check also runs the existing local AI-image model on the original upload, using the same preprocessing as /v1/detect-ai-image. This adds a separate model inference. Nudity screening uses the same local policy as /v1/moderate-photo. nudity.confidence is its strongest policy detection score as a percentage, nudity.threshold is the threshold used as a percentage (default 45), and nudity.reasons explains a flag. Only a local allow result yields nudity.passed: true; possible and explicit nudity flags both prevent a profile-photo match. The API uses the account photo screening threshold; the playground slider is test-only. No external nudity fallback is used. An unavailable, busy, timed-out or malformed face, AI, nudity, age or OCR check returns an unavailable error with no partial result. Historical v1/v2/v3/v4/v5 idempotent replays retain their original response without age or OCR/contact fields; v1/v2/v3/v4 also omit nudity fields; v1/v2/v3 also omit AI confidence; v1/v2 also omit face fields; use a new key to request the current check. Invalid or unavailable processing returns an error without a category or confidence; it is not an approval.

Images are processed locally and discarded. Structured results, including recognized text and possible contact details, follow the existing 30-day replay retention. Playground usage history keeps only a minimal outcome summary; downloaded exports include the recognized text. This endpoint must be enabled by the service operator after the classifier worker is provisioned.

Example response · HTTP 200

{
  "ageEstimates": [],
  "aiGeneratedConfidence": 77.45,
  "category": "clothing_merchandise",
  "confidence": 82.5,
  "contactDataDetected": true,
  "contactSignals": {
    "email": true,
    "link": false,
    "phone": false,
    "socialHandle": false
  },
  "creditsCharged": 0,
  "elapsedMs": 125.4,
  "error": null,
  "faceCount": 0,
  "faceDetected": false,
  "isProfilePhoto": false,
  "nudity": {
    "confidence": 0,
    "passed": true,
    "policyVersion": "dating-photo-v1",
    "reasons": [],
    "threshold": 45
  },
  "ok": true,
  "operation": "profile-photo",
  "policyVersion": "profile-photo-v6",
  "possibleMinor": null,
  "rawText": "Contact: hello@example.com",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "scores": {
    "animal": 1.2,
    "cartoon": 1.2,
    "clothing_merchandise": 82.5,
    "footwear_merchandise": 1.2,
    "landscape_or_object": 1.2,
    "meme": 1.2,
    "personal_photo": 1.2,
    "poster": 1.2,
    "product": 1.2,
    "screenshot": 1.2
  },
  "status": "completed",
  "textDetected": true
}

Credits & safe retries

Successful image analysis consumes the listed cost even if no face, photo text, or nudity is detected. Text moderation beta, AI-generated image detection and profile-photo classification cost zero paid checks; failed analysis also consumes zero credits. Completed analysis responses include requestId and creditsCharged.

All API requests require an Idempotency-Key header (8–100 characters: letters, digits, dots, colons, underscores, hyphens). Retrying the same endpoint and payload with that key returns the original completed result without another charge. Reusing it for a different payload returns HTTP 409. Retry a temporary unavailable result with the same key; to rerun a completed failed analysis, use a new key.

Credit grants, payments, and usage are recorded in a ledger. Subscription credits are added only after a verified successful PayPal payment, never just because a browser returns from checkout. Cancelling stops renewals; unused credits remain. Refunds and reversals withdraw the related payment’s credits; partial refunds require administrator reconciliation.

Errors & limits

Example temporary error · HTTP 503

{
  "creditsCharged": 0,
  "detail": "Analysis temporarily unavailable. Keep the content pending review.",
  "error": "unavailable",
  "moderation": {
    "decision": "unavailable",
    "reasons": [
      "unavailable"
    ],
    "reviewRequired": true
  },
  "ok": false,
  "operation": "analyze-face",
  "requestId": "d2893b02-37a9-428f-84ed-283589cf784b",
  "scores": {},
  "status": "failed"
}

Keep the content pending and retry after Retry-After when provided. All error responses charge zero credits.

StatusMeaning
400Invalid request or missing idempotency key
401Missing, invalid, or revoked API key
402Insufficient credits
403Account disabled
409Idempotency key conflict
413Image or request too large
422Invalid input or analysis failed
429Rate limit reached
503Analysis temporarily unavailable; no credits charged

Image requests allow up to 12 MiB decoded per image and 25 MiB for the total JSON request, with up to six candidate images for comparison. Text beta limits are listed above. API requests allow a maximum of 60 new requests per minute per customer, plus a server-level IP limit. Allow up to 130 seconds for an image request; requests for one customer are processed serially to keep charging consistent.

Data handling

Images are processed in temporary files and deleted after analysis. Images and face embeddings are not stored in the customer database. Structured image responses, including any extracted photo text and age estimates, are retained for 30 days for retry handling. Native text beta results omit submitted text and matched addresses and numbers; their generic responses are retained for 30 days. The customer dashboard shows daily API and playground operations and charged credits for 7, 14, 30 or 90 days, plus details for the latest 50 requests. Moderation outcomes are retained for up to 30 days alongside response bodies; older history labels expired outcomes explicitly. An unavailable or failed request is never shown as approved. Playground history retains only limited outcome summaries and zero-credit accounting. For new requests, history includes source IP and limited input metadata, such as image byte estimates or text length and context. Submitted images and native text cannot be viewed or recovered there. Source IP is cleared after 30 days by daily maintenance. Encrypted disaster-recovery backups expire after seven days; a deleted response or source IP can therefore remain in a backup for up to seven additional days. Usage metadata and the credit ledger remain for accounting. A retry after result expiry returns 410 without charging; use a new key to analyze again.

Only submit content you’re authorized to process. Keep submitted content out of your own application logs, and treat analysis outputs as personal data where applicable.