Author: 
There is a specific moment in every vibe coding session where the model stops being able to help. You describe a skin analysis website, the agent scaffolds the project, writes the upload component, builds the results page, styles the score cards, handles the loading states, and produces something that looks finished. Then you upload a photograph of a face and discover the one thing it quietly faked: the analysis.
This is not a failure of the model. It is a category boundary, and understanding where it sits is the difference between a demo and a product. A language model can build everything around a skin measurement. It cannot perform one. This article builds a working skin analysis website with that boundary made explicit, using an agent for the ninety percent it is genuinely good at and the YouCam Skin Analysis API for the ten percent it cannot touch.
Why an LLM Cannot Analyse Skin
Worth being precise, because "AI can see images now" makes this sound wrong. A general vision model can look at a face and produce a fluent paragraph about it. What it cannot produce is a number that means the same thing twice.
| Property | General vision model | Purpose built skin analysis |
|---|---|---|
| Output | Descriptive text, phrased differently each time | Numeric scores on a fixed scale |
| Repeatability | Same photo, different answer on a second run | 95% test to retest reliability |
| Comparability over time | None. Nothing to subtract from anything | The entire point. Month to month deltas |
| Region specificity | Approximate, described in prose | Seven wrinkle regions, four pore regions, scored separately |
| Validation | Not validated for this task | Over 80% correlation with physician assessment, peer reviewed |
| Skin tone coverage | Unknown and untested | Validated across the Fitzpatrick range |
The second row is the one that kills a product. A skin analysis app whose entire proposition is "see your progress" cannot be built on something that returns a different answer for the same photograph. Everything else on that list is a quality concern. Repeatability is an existence concern.
A measurement instrument's usefulness for tracking change depends first on its test to retest reliability, since without it any observed difference between two timepoints cannot be distinguished from measurement noise.Bland, J. M. and Altman, D. G., Statistical methods for assessing agreement between two methods of clinical measurement, The Lancet
What You Are Building
| Layer | What it does | Who writes it |
|---|---|---|
| Capture | Upload or camera, with lighting and framing guidance | The agent, from your requirements |
| Validation | Rejects images that cannot produce a usable score | The agent, from the documented limits |
| Analysis | Returns 28 diagnostics across 16 skin concerns | The API. Nothing else can do this |
| Results UI | Score cards, region overlays, ranked concerns | The agent, and it is good at this |
| Interpretation | Plain language explanation of what the scores mean | The API's Insight Report, or your own copy |
| Recommendations | Products mapped to concerns and score bands | Your catalogue, your rules |
| History | Stores scans and plots change over time | The agent, and this is where the value lives |
What You Need Before You Start
| Requirement | Detail |
|---|---|
| API key | Free from the YouCam API Console, with 40 free units for testing |
| Image input | An uploaded photograph or a live camera capture, front facing, bare face, even indirect light, no flash |
| An async pattern | Analysis returns a task id, then you poll for the result |
| A retention plan | Results are held for 24 hours. Persist what you need inside that window |
| Somewhere to store history | A database. Without it you have a toy, not a product |
Connecting the Agent to the API
The fastest way to collapse the gap between "the agent is guessing" and "the agent has seen a real response" is to give it the API directly while it writes. The YouCam MCP server does that.
claude mcp add youcam-beauty \
-- npx -y mcp-remote https://mcp-api-01.makeupar.com/mcp/beauty \
--header "Authorization: Bearer YOUR_API_KEY"Run one analysis in the conversation before asking for any code. The agent then builds the results UI against the actual response shape rather than an invented one, which removes the single most common source of rework in this kind of build. If you would rather stay in a terminal, the YouCam CLI reaches the same endpoints, and YouCam API Agent Skills cover the agent side.
The Capture Step Is Where Products Fail
An agent will build you a file input in seconds. It will not, unprompted, build the thing that actually determines whether your scores are worth anything. Capture conditions move skin analysis results more than most developers expect, and every one of the constraints below has to be enforced before the image is accepted rather than apologised for afterwards.
| Constraint | Why it matters | What happens if you skip it |
|---|---|---|
| No flash | Flash removes the micro shadowing that makes texture and pores visible | Falsely high texture scores. The customer's best score is their worst photo |
| Even indirect light | A single hard source reads as shine, an overhead source invents under eye shadows | Oiliness and eye area scores track your lighting, not the skin |
| Bare face | Powder suppresses oiliness, highlighter inflates it, foundation hides texture | Every reading is measuring makeup |
| Face fills the frame | Regions need enough pixels to be scored separately | Region level scores degrade first, silently |
| Eye level camera | A low angle exaggerates lower face descent | Firmness comparisons measure your phone position |
| Neutral expression | A smile deepens several wrinkle regions | Wrinkle scores swing between scans for no real reason |
| Consistent time of day | Sebum output varies across the day | Re-scans are not comparable, which breaks the whole proposition |
Tell the agent these constraints explicitly and it will build the guard rails well. Leave them out and you get a file input, a spinner, and a results page full of numbers that mean nothing. This is the clearest example of the general pattern: the agent executes excellently and specifies nothing.
The Analysis Call
Submit the image, receive a task id, poll until it resolves. Nothing exotic, and the agent will write the retry and backoff logic correctly if you mention the 24 hour result retention and ask it to persist what you need.
// 1. Submit
const { task_id } = await submitAnalysis(imageFile);
// 2. Poll until resolved
const result = await pollUntilDone(task_id, { intervalMs: 2000 });
// 3. Persist immediately. Results expire in 24 hours.
await db.scans.insert({
userId,
capturedAt: new Date(),
scores: result.scores,
// store the mask images yourself if you display them later
});The comment on the last line is the part to not skip. Everything the API returns is ephemeral. If your history feature reads from the API rather than from your own database, it works for a day and then quietly stops.
What Comes Back
| Output | Detail |
|---|---|
| Concern scores | 28 diagnostics across 16 concerns, each on a 1 to 100 scale where higher is healthier |
| Wrinkle regions | Forehead, glabellar, crow's feet, periocular, nasolabial, marionette and whole face, scored independently |
| Pore regions | Forehead, nose, cheek and whole face |
| Skin type | Whole face, T zone and U zone separately, which is what identifies combination skin |
| Skin age | A composite figure built from the contributing scores |
| Detection masks | PNG images you can overlay on the original photograph |
| AI Skin Insight Report | A written per person explanation with contributing factors and daily care steps |
| Recommendations | Products from your own configured catalogue, mapped to concerns and bands |
The last two rows are recent additions and they change what you have to build. Before them, the explanation layer and the product mapping were yours to write, which is where most of the copywriting and rules work went. Now the report arrives with the scores. The release notes cover what ships in it, including the contributing factors ranking and the photo limitation card.
Designing the Results Page
The agent will happily render all 28 numbers in a grid. Do not let it. A results page that shows everything with equal weight transfers the entire interpretation burden to a person who came to you specifically because they could not do that themselves.
| Do | Instead of |
|---|---|
| Lead with a ranked top three concerns | A grid of 28 equal tiles |
| Show band labels alongside numbers | A bare figure like 61 with no scale |
| Offer the detection mask as a toggle | Hiding what produced the score |
| Name a realistic timeframe per concern | Implying everything moves at the same speed |
| Keep the photo limitation and the disclaimer visible | Stripping them out because they look untidy |
| Open the next scan with a comparison | Treating each scan as a fresh unrelated event |
The timeframe row prevents the most common abandonment. Texture moves in four to twelve weeks, pigment in three to six months, firmness in six to twelve. A results page that invites a re-scan in thirty days without saying which concerns could plausibly have changed sets the customer up to conclude that nothing works.
Where the Agent Is Strong, and Where It Is Not
| Task | Verdict |
|---|---|
| Project scaffolding, routing, state, styling | Excellent. This is the bulk of the work and it disappears |
| Upload, polling, retries, error states | Excellent, once you state the retention limits |
| Score card and chart components | Excellent, and fast to iterate on |
| Database schema for scan history | Good. Review the indexing if you expect volume |
| Deciding which capture constraints to enforce | Weak unless told. It will not derive these from the task |
| Deciding what to show and what to rank | Weak. It defaults to showing everything |
| Measuring the skin | Impossible. Not a weakness, a category difference |
| Knowing whether the scores are plausible | Impossible. Scan a known face and check yourself |
Read that table as a division of labour rather than a list of complaints. The agent handles execution. You supply specification and judgement. The API supplies the measurement. A build goes wrong when someone assumes the agent covers all three.
Testing Before You Ship
Scan the same face twice, five minutes apart, same conditions. The scores should barely move. If they swing, your capture flow is not controlling what it needs to.
Scan with flash and without. Watch the texture score change. Then confirm your app refuses the flash image rather than scoring it.
Scan across the Fitzpatrick range. Not just the development team. This is the test most teams skip and the one with the largest consequences.
Let a result expire. Confirm your history feature reads from your database and not from a URL that stopped working overnight.
The skin analysis playground runs all four checks before you write a line of code, and the API documentation has the full field definitions.
Responsible Use
Three rules, and they are not optional decoration.
Do not present it as a diagnosis. It is a cosmetic assessment of visible signs. The disclaimer ships with the response and should survive your restyling.
Do not strip the photo limitation. Where capture conditions limited what could be resolved, say so. A user who is told where the analysis is uncertain trusts the parts that are confident.
Do not infer health. Contributing factors describe appearance and its likely drivers. They are not conditions, and nothing in the output should be presented as a reason to start or stop a medical treatment.
FAQ
Can a general purpose AI model do skin analysis on its own?
It can describe a face fluently. It cannot return a repeatable number, which is what tracking change requires. The same photograph analysed twice will produce different prose, and nothing meaningful can be subtracted from that.
What does the Skin Analysis API return?
28 diagnostics across 16 skin concerns on a 1 to 100 scale, with wrinkles scored across seven regions and pores across four, plus skin type by zone, a skin age composite, detection masks, the AI Skin Insight Report and product recommendations from your configured catalogue.
How accurate is it?
95% test to retest reliability and over 80% correlation with professional physician assessment, trained on 70,000+ clinical images and examined across four peer reviewed journal publications, with validation across the Fitzpatrick range.
Do I need Claude Code or MCP?
No. It is a standard API with bearer authentication. MCP is a convenience that lets an agent call the API while writing your app, which mainly saves rework on the response shape.
How long are results available?
24 hours. Persist anything you need, including mask images, into your own storage inside that window.
What is the most common mistake in these builds?
Shipping a capture step with no constraints. The integration is straightforward and the scores are only as good as the photograph, so most of the quality work sits before the API call rather than after it.
How much does it cost?
Units are consumed per successful analysis with volume based pricing, and 40 free units to start. The pricing page and unit calculator give a figure against expected volume.
Is this a medical product?
No. It is a cosmetic skin assessment intended to guide product selection and track visible change, and it does not replace evaluation by a healthcare professional.
Conclusion
Vibe coding a skin analysis website is genuinely fast now, and the speed is real rather than a demo artefact. What has not changed is where the measurement comes from. An agent can build the capture flow, the results page, the history charts and the recommendation interface, and it can do all of it in an afternoon. It cannot look at a cheek and tell you a number that will still mean the same thing next month.
Build the part the agent is good at with the agent. Buy the part it cannot do. And spend the time you save on the capture step, because that is where the difference between a convincing product and a plausible looking one actually sits.
Get a free API key and run one scan before writing any code, or talk to our team about deployment.
