API DOCUMENTATION

Build facial intelligence into your product.

The public documentation describes Toon Tech’s developer contract and data model. Approved partners receive production credentials, endpoint details and integration support.

Request sandbox access Quickstart ↓

API MODEL

Asynchronous analysis

Submit an analysis request, receive an analysis ID, then poll or use a webhook for completion.

INPUTUser-authorized image

OUTPUTStructured JSON

AUTHBearer API key

01 · OVERVIEW

A modular facial-analysis API.

Toon Tech exposes facial intelligence as structured modules rather than a fixed consumer interface. Partners select the analysis they need and use the returned fields inside their own product logic, scoring presentation or personalization workflow.

Example host

https://api.toontech.example is used in public examples. Approved partners receive the current production host and credentials.

02 · QUICKSTART

Submit an image and choose modules.

POST/v1/analyses

curl -X POST https://api.toontech.example/v1/analyses \
  -H "Authorization: Bearer $TOONTECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/user-photo.jpg",
    "modules": ["geometry", "symmetry", "proportions"],
    "context": "grooming",
    "webhook_url": "https://yourapp.com/webhooks/toontech"
  }'

Accepted response

{
  "id": "analysis_8f24c1",
  "status": "queued",
  "created_at": "2026-08-10T10:00:00Z"
}

03 · AUTHENTICATION

Bearer-key authentication.

Production requests include a partner API key in the Authorization header.

Authorization: Bearer tt_live_••••••••••••

Keep API keys on your server. Do not embed production credentials in client-side mobile or browser code.

04 · CREATE ANALYSIS

Request fields.

Field	Type	Required	Description
`image_url`	string	yes*	HTTPS URL for a user-authorized image.
`image_base64`	string	yes*	Base64 image payload when URL delivery is not used.
`modules`	array	yes	Analysis modules requested for this job.
`context`	string	no	Product context such as beauty, grooming or general analysis.
`webhook_url`	string	no	HTTPS callback for asynchronous completion.

*Provide one image source, not both.

05 · RETRIEVE ANALYSIS

Poll by analysis ID.

GET/v1/analyses/{analysis_id}

curl https://api.toontech.example/v1/analyses/analysis_8f24c1 \
  -H "Authorization: Bearer $TOONTECH_API_KEY"

Completed response

{
  "id": "analysis_8f24c1",
  "status": "completed",
  "face": {
    "shape": "oval",
    "geometry": { "signals": { "...": "..." } },
    "symmetry": { "signals": { "...": "..." } },
    "proportions": { "signals": { "...": "..." } }
  },
  "meta": {
    "modules": ["geometry", "symmetry", "proportions"],
    "model_version": "partner-current"
  }
}

06 · MODULES

Choose only what your product needs.

Geometry

Normalized landmarks, region distances, ratios and face-shape signals.

geometry

Symmetry

Structured left/right correspondence and balance measurements for application logic.

symmetry

Proportions

Relationships between facial thirds, widths, feature spacing and other geometry.

proportions

Appearance

Non-sensitive visual signals used in beauty, grooming and presentation experiences.

appearance

Scoring

Task-specific structured scoring systems built from defined model outputs.

scoring

Personalization

Fine-tuned language-model outputs that convert structured analysis into product-specific guidance.

personalization

07 · RESPONSE MODEL

Structured fields, partner-owned UX.

The API returns structured data so each application can create its own interface and business logic. Toon Tech does not force one universal consumer score or presentation.

Personalization module

Where enabled for an approved use case, a fine-tuned language-model layer can transform structured analysis into product-specific explanations or recommendations. The application remains responsible for the final presentation and product claims.

08 · ERRORS

Predictable HTTP errors.

Status	Code	Meaning
400	`invalid_request`	Malformed JSON or unsupported field.
401	`unauthorized`	Missing or invalid API key.
413	`image_too_large`	Image exceeds partner limits.
422	`image_unprocessable`	No suitable face or unusable image.
429	`rate_limited`	Partner rate limit exceeded.
503	`temporarily_unavailable`	Analysis service temporarily unavailable.

09 · DATA & PRIVACY

User-authorized inputs only.

Partners are expected to collect appropriate user permission for images they submit. Production retention, security controls, deletion workflows and regional processing requirements are defined with each approved integration.

The public API story is not positioned as identity recognition or surveillance.
The platform is not marketed as medical diagnosis.
The developer surface is not positioned for inferring protected or highly sensitive personal traits.
Partner applications remain responsible for their own end-user notices, consent and lawful use.