Ollie API
A free JSON API for outfits and haircuts: dress an AI model (4 body types, 6 looks) in real clothes from the Ollie catalogue, and get the 3 best haircuts for any of 7 face shapes. No key needed. Ollie Pro keys add face shape from a photo and AI try-on.
Quick start
Base URL https://www.ollieml.com/api/v1. JSON in, JSON out, CORS open, so it works from a browser too. No key for the free endpoints:
curl -X POST https://www.ollieml.com/api/v1/outfit -H "Content-Type: application/json" \ -d '{ "gender": "female", "build": "athletic", "style": "old-money" }'const res = await fetch("https://www.ollieml.com/api/v1/outfit", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ occasion: "date", build: "slim" }),})const outfit = await res.json()console.log(outfit.items.map((i) => `${i.name} (${i.color}) ${i.price}`))Free and Pro
- Free, no key: catalog, outfit, haircuts. Pure rules and real catalogue data, so they're free to run and free to call.
- Pro key: face-shape (a face-mesh model) and try-on (an AI image edit). Send
Authorization: Bearer ollie_sk_…from an account with Ollie Pro. Create keys on your account; Pro is on the Ollie Stylist.
Endpoints
GET /api/v1/catalog Free
Everything the editor offers: models (gender, build, look), styles, occasions, budgets, every clothing piece with its id, price and colours, and the face options the try-on accepts. Filter with ?slot=top|outer|bottom|shoes and ?gender=male|female.
curl "https://www.ollieml.com/api/v1/catalog?slot=shoes&gender=male"{ "models": {...}, "styles": [...], "occasions": [...], "budgets": [...], "items": [{ "id": "nb-550", "slot": "shoes", "name": "New Balance 550", "price": "$109.99", "colors": [] }, ...], "face": { "hair": [...], "brows": [...], "beard": [...], "glasses": [...] } }POST /api/v1/outfit Free
Dresses the model. Give a style (Choose for me), an occasion (Dress for), a budget and/or exact pieces and colours; pieces are laid over the style or occasion picks, and "none" takes a slot off. Returns each piece with its colour, price and shop link, the total, styling notes, the image layers to stack (bottom first) and a link that opens the outfit in the Ollie editor.
curl -X POST https://www.ollieml.com/api/v1/outfit -H "Content-Type: application/json" -d '{ "gender": "male", "build": "plus", "look": "black", "occasion": "interview", "budget": "mid", "items": { "shoes": "clarks-desert-boot" }, "colors": { "shoes": "Sand Suede" }}'{ "model": { "gender": "male", "build": "plus", "look": "black" }, "items": [{ "slot": "top", "id": "uniqlo-dress-shirt", "name": "Uniqlo Easy Care Stretch Slim Shirt", "color": "White", "colors": [{ "name": "White", "hex": "#f0f0f4" }, ...], "price": "about $40", "shop": "https://..." }, ...], "total_usd": 512, "notes": ["..."], "problems": [], "layers": [{ "src": "https://www.ollieml.com/style/models/male-plus-black.jpg?v=..." }, { "src": ".../top.webp", "mask": ".../clip.webp", "tint": "#c7a37a" }, ...], "editor_url": "https://www.ollieml.com/ai-stylist?look=...", "name": "Job interview" }POST /api/v1/haircuts Free
The 3 best haircuts for a face shape (oval, round, square, oblong, heart, diamond, triangle), with what to ask the barber, how to style it and how often to trim, plus glasses, brows, beard styles and fit notes. Optional: gender, age, hair_texture, hairline, goal, height_cm, build.
curl -X POST https://www.ollieml.com/api/v1/haircuts -H "Content-Type: application/json" -d '{ "face_shape": "round", "gender": "male", "hair_texture": "wavy" }'{ "face_shape": "round", "haircuts": [{ "id": "quiff", "name": "Quiff", "why": "...", "ask_the_barber": "...", "styling": [...], "trim_every_weeks": 4 }, ...], "glasses": [...], "brows": [...], "beard": [...], "fit_notes": [...] }POST /api/v1/face-shape Pro key
The face shape from a straight-on photo (478-point face mesh), then the same picks as /haircuts. Uses one of the account's 25 daily photo searches. image: a data: URL (base64) or a public https URL.
curl -X POST https://www.ollieml.com/api/v1/face-shape -H "Authorization: Bearer $OLLIE_KEY" \ -H "Content-Type: application/json" -d '{ "image": "https://example.com/me.jpg", "gender": "female" }'{ "face_shape": "heart", "face_shape_label": "heart, close to oval", "confidence": 0.71, "haircuts": [...], "glasses": [...], "searches_left_today": 24 }POST /api/v1/try-on Pro key
Edits the user's own photo to show them with a haircut, brows, beard, glasses and/or clothes (ids from /catalog), keeping their face, body and background. 15 a day per account. The photo goes to Google's Gemini image model for the edit and isn't stored by Ollie. Only for photos of the person using your app, with their consent.
curl -X POST https://www.ollieml.com/api/v1/try-on -H "Authorization: Bearer $OLLIE_KEY" \ -H "Content-Type: application/json" -d '{ "image": "data:image/jpeg;base64,/9j/4AAQ...", "hair": "textured-crop", "items": { "top": "uniqlo-merino-crew", "outer": "alpha-ma1" }, "colors": { "top": "Navy" }}'{ "image": "data:image/png;base64,iVBORw0..." }Errors and limits
Errors are { "error": "…", "code": "…" } with these statuses:
400 bad_requestThe body didn't validate. error says which field.401 key_required / bad_keyA Pro endpoint got no key, or a key that doesn't exist.402 pro_requiredThe key's account doesn't have Ollie Pro.422 no_face / head_turnedNo face in the photo, or the head is turned too far for a reliable face shape.429 rate_limited / limitOver 120 requests a minute from one IP, or the account's daily photo or try-on limit.
Limits: 120 requests a minute per IP; 25 photo searches a day per account (shared with ollieml.com and the ChatGPT apps); 15 try-ons a day per Pro account. Photos are processed in memory and never stored.
Questions
Is the Ollie API free?
Yes. /catalog, /outfit and /haircuts are free, need no key and no sign-up, and allow 120 requests a minute per IP. Only the endpoints that run a model on a photo (face shape and AI try-on) need a key from an Ollie Pro account.
How do I get an API key?
Sign in on ollieml.com, open Account, then API keys, and select Create key. The key is shown once. Each account can have 5.
Can I use the outfit images in my app?
Yes. Stack the layers array in order (absolutely positioned images of the same size); where a layer has a mask, clip it to that image's alpha, and where it has a tint, recolour it to that hex or show the piece in its default colour. Or link to editor_url, which opens the same outfit in the Ollie editor.
Is there a celebrity lookalike API?
No. Lookalike and face comparison are for people's own photos inside Ollie's site and its ChatGPT and Claude apps, so they aren't offered as an API.
Do shop links earn a commission?
Clothing shop links go to each brand's own site. Haircut product links are Amazon affiliate links, and Ollie may earn a commission on them.
Using ChatGPT or Claude instead of code? Connect the Ollie MCP servers.