API Reference

The superstyle API is organized around REST. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Just getting started? Check out our quickstart guide to make your first API call in under 5 minutes.

Security & Privacy

Your data is safe

Our API handles sensitive data like selfies and personal photos. We take this seriously:

• Ephemeral images — generated images auto-delete after 24 hours by default. Temporary files are automatically cleaned up.
• No training on your data — your images and requests are never used to train models.
• Encrypted in transit — all API traffic is served over HTTPS/TLS.
• API keys are hashed — keys are stored as irreversible hashes, not plaintext.

Read the full Security & Data guide for details on our data handling practices.

Base URL

All API requests are made to:

https://mcll3bnfubyazfg6wekv3xc6fi0dgpyk.lambda-url.us-east-1.on.aws

Authentication

Authenticate your requests by including your API key in the X-API-Key header. You can generate and manage API keys from the Developer Portal.

All API requests (except the health check endpoint) must include a valid API key. Requests without authentication will return a 401 Unauthorized error. Requests with an invalid key will return 403 Forbidden.

curl -X POST https://mcll3bnfubyazfg6wekv3xc6fi0dgpyk.lambda-url.us-east-1.on.aws/analyze_outfit \
  -H "X-API-Key: ss_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/outfit.jpg"}'

For more details, see Authentication.

Endpoints

Endpoint	Method	Description	Docs
/	GET	Health check — verify the API is running	—
/try_on_outfit	POST	Generate a realistic image of a person wearing an outfit, from a reference image and/or description	View
/images	GET	List all generated images for your account	View
/images/:id	GET	Get metadata for a specific generated image	View
/analyze_outfit	POST	Analyze an image and identify individual clothing items	View
/style_me	POST	Get personalized outfit recommendations (Swag Mode)	View
/usage	GET	View your API usage statistics	View

Response format

All successful responses return a 200 status code with a JSON body. The shape of the response depends on the endpoint — see individual endpoint docs for details.

{
  "items": [...],
  "metadata": { ... }
}

Error handling

When an error occurs, the API returns a JSON object with an error field describing what went wrong:

{
  "error": "Missing required field: image_url"
}

Rate limits

All endpoints except /usage are rate limited to 20 requests/day per user with a maximum of 1 concurrent request. Exceeding the limit returns 429 Too Many Requests.

See Rate Limits for full details, headers, and retry examples.

Status codes

Code	Description
200	OK — Request succeeded
400	Bad Request — Missing or invalid parameters
401	Unauthorized — No API key provided
403	Forbidden — Invalid or revoked API key
404	Not Found — Endpoint does not exist
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Something went wrong on our end