Getting Started

Get up and running with the FuturaSmile API in minutes. Our REST API enables effortless integration of premium smile simulations into your products.

Step 11

Register Platform

Create an account on the FuturaSmile console to gain authorization and provision a unique credentials token.

Step 22

Choose a Plan

Choose a subscription tier directly within the console dashboard to match your volume, speed, and SLA needs.

Select subscription tier

Step 33

Make First API Call

Invoke our endpoint utilizing your key inside standard REST clients or from your application backend servers.

See REST code examples

Authentication

The FuturaSmile API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Required Authorization Header

Include a standard Authorization header containing the exact active prefix "Bearer " followed by your credentials key.

Authorization: Bearer fsk_your_api_key_here

Request Troubleshooting Header

Every API response (both successful results and errors) contains a unique X-Request-ID header. If you encounter issues, please log and provide this ID to support for rapid troubleshooting.

POST/api/v1/generateAlignment

Takes a smile photograph encoded in base64 format, processes the input through the FuturaSmile imaging engine, and returns a realistic smile preview simulating natural tooth alignment improvements.

curl -X POST https://api.futurasmile.com/api/v1/generate \
  -H "Authorization: Bearer fsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }'

Request Body Parameters

imagestringrequired

A base64 encoded string representing the smile photograph. Can be passed raw or prefixed with standard data URIs (e.g. data:image/png;base64,...).

💡 Limits: Maximum decoded image size is 10 MB.
Aspect Ratio: Strictly 1:1 (square) required. Non-square images are rejected.
Allowed types: image/png, image/jpeg, image/jpg, image/webp, image/gif, image/heic, image/heif.

Response Fields (200 OK)

successboolean

Indicates whether the generation succeeded.

imagestring

The generated smile preview returned as a base64-encoded image string.

mimeTypestring

MIME type of the generated visual (e.g. "image/png").

usageobject

Quota usage metrics including generations_used, generations_included, and generations_remaining.

POST/api/v1/generate/cosmeticCosmetic

Takes a smile photograph encoded in base64 format and returns a premium cosmetic enhancement simulation — realistic shade adjustments and alignment aesthetics while preserving natural proportions. Uses the same authentication and validation as the alignment endpoint.

Alignment vs Cosmetic Mode

Both endpoints utilize the same FuturaSmile simulation pipeline. The primary distinction is the visualization focus:
/api/v1/generate — Smile alignment simulation (natural tooth positioning refinement)
/api/v1/generate/cosmetic — Cosmetic enhancement simulation (shade adjustment, alignment aesthetics, premium finish)

curl -X POST https://api.futurasmile.com/api/v1/generate/cosmetic \
  -H "Authorization: Bearer fsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }'

Request Body Parameters

imagestringrequired

Identical to the alignment endpoint. A base64 encoded string representing the smile photograph. Can be passed raw or prefixed with standard data URIs.

💡 Same limits apply: Maximum decoded image size is 10 MB.
Aspect Ratio: Strictly 1:1 (square) required. Non-square images are rejected.
Allowed types: image/png, image/jpeg, image/webp, image/gif, image/heic, image/heif.

Response Fields (200 OK)

successboolean

Indicates whether the generation succeeded.

modestring

Always "cosmetic" for this endpoint. Distinguishes from alignment responses.

imagestring

The generated cosmetic preview returned as a clean base64-encoded image string.

mimeTypestring

MIME type of the generated visual (e.g. "image/png").

usageobject

Quota usage metrics. Both endpoints share the same monthly quota.

GET/api/v1/usage

Returns the current billing cycle metrics, included quota boundaries, active tier name, remaining balances, and active tracking dates.

curl -X GET https://api.futurasmile.com/api/v1/usage \
  -H "Authorization: Bearer fsk_your_api_key_here"

Response Fields (200 OK)

plan_typestring

The name of the subscribed plan tier.

generations_includedinteger

Included quota allowances in the cycle.

generations_usedinteger

Number of generations consumed in the current tracking period.

generations_remaininginteger

Remaining generation balance.

billing_cycle_startstring (date)

Date format YYYY-MM-DD representing the start of the current cycle.

Example Response JSON

200 OK

{
  "plan_type": "starter",
  "generations_included": 150,
  "generations_used": 12,
  "generations_remaining": 138,
  "billing_cycle_start": "2026-05-23"
}

Error Handling & Codes

All error responses follow a consistent JSON structure with standardized status codes and developer-friendly messages.

Standard Error Payload Shape

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unsupported image type: image/tiff. Allowed: image/png, image/jpeg, image/jpg, image/webp, image/gif"
  }
}

HTTP Status	Error Code	Trigger Scenarios
400 Bad Request	VALIDATION_ERROR	Malformed JSON bodies; missing or non-string image data; invalid base64 schemas; size > 10MB; or unsupported MIME types.
400 Bad Request	OPTIMIZATION_FAILED	The uploaded image could not be processed. Please verify the file is not corrupted and uses a supported format.
401 Unauthorized	UNAUTHORIZED	Missing or malformed Authorization header, invalid API key, or revoked credentials.
403 Forbidden	FORBIDDEN	Access denied. Your request does not meet the required access conditions.
403 Forbidden	NO_SUBSCRIPTION	Active subscription required. No active subscription is associated with this API key.
404 Not Found	NOT_FOUND	The requested resource or endpoint could not be found.
413 Payload Too Large	PAYLOAD_TOO_LARGE	The request payload exceeds the maximum allowed size of 10 MB.
422 Unprocessable Entity	IMAGE_NOT_SUITABLE	The uploaded image does not meet the required format criteria. Please ensure the image has a 1:1 (square) aspect ratio and the photo includes a clearly visible, front-facing smile.
429 Too Many Requests	RATE_LIMITED	Rate limit exceeded. Please reduce request frequency or upgrade your plan.
429 Too Many Requests	QUOTA_EXCEEDED	Monthly generation limit for your plan has been exhausted. Upgrade your plan or wait until the next billing cycle.
500 Server Error	INTERNAL_ERROR	An unexpected error occurred. Please retry your request or contact support if the issue persists.

Plans & Limits

Compare limits and quotas of active plan tiers. Switch tiers easily in the user console dashboard.

StarterStandard

$99/mo

Ideal for small platforms and testing.

150 included generations/mo
Standard API concurrency
Single credentials token
Email customer support

RECOMMENDED

StudioPopular

$299/mo

Built for growing platforms and production.

600 included generations/mo
Priority processing
Multi-key credentials support
Priority support (<12 hour SLA)

Upgrade Now

EnterpriseCustom

Contact Sales

SLA-guaranteed pricing, custom volumes, and dedicated imaging infrastructure.

Custom included volume
SLA guaranteed limits & throughput
Dedicated infrastructure
Enterprise security & data protection
24/7 account manager

Contact Sales

Quota Limits & Enforcement

We enforce strict usage limits to maintain API performance and service stability. If your monthly consumption reaches the generation quota limit of your plan, subsequent requests will be blocked and return a QUOTA_EXCEEDED error code (HTTP 429) before processing. You can upgrade your subscription tier in the console dashboard to increase limits, or wait until your billing cycle resets.