API guides / Stylist

A personal point of view.

Turn customer preferences into recommendations from your own prepared product catalog.

A two-step styling journey

Analyze the customer’s preferences, with an optional photo. Then pass the returned body analysis, the preference text, and your prepared products to the recommendation endpoint.

Preferences→Customer analysis→Catalog recommendations

Analyze the customer

POST/v1/styling/analyze-customer

Field	Type	Usage
`preference_text`	string	Required. The customer’s preferences, occasion, or styling request.
`photo_url`	string	Optional. Accessible HTTPS URL of the customer photo.

Customer analysis body

{
  "preference_text": "An effortless look for a gallery opening"
}

The response wraps the analysis in result, alongside credits_charged and credits_available. The integration passes result.body_analysis into the recommendation request. Retain the structured analysis instead of replacing it with a written summary.

Prepare your catalog

Recommendations use product records with these fields in the integration:

Field	Type	Usage
`id`	string	Your stable product identifier.
`category`	string	Product category or descriptive product label.
`garment_types`	string[]	Prepared garment categories.
`target_gender`	string	The catalog product’s target audience.
`style_attributes`	object	Structured attributes generated during catalog preparation.
`color_variants`	array	Prepared color attributes for available variants.

Arrange extraction and validate the exact nested schema with BeforeAI before integration. Do not pass raw storefront records or invent style attributes. The integration excludes products whose extraction has not completed.

Keep product IDs stable so your interface can resolve recommended IDs to product names, photos, prices, and availability from your own catalog.

Recommend from your products

POST/v1/styling/recommend

Field	Type	Usage
`preference_text`	string	Required. Customer styling request.
`body_analysis`	object or null	Customer analysis used by the integration; preserve the returned structure.
`products`	array	Your prepared catalog records.
`customer_target_gender`	string	Optional customer audience filter; the existing frontend uses women, men, or kids.

Server-side recommendation payload

// analysisResponse: successful analyze-customer response
// preparedProducts: catalog records validated during onboarding
const payload = {
  preference_text: preferenceText,
  body_analysis: analysisResponse.result.body_analysis ?? null,
  products: preparedProducts,
};

const response = await fetch(
  `${process.env.BEFOREAI_GATEWAY_URL}/v1/styling/recommend`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.BEFOREAI_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  },
);
if (!response.ok) {
  throw new Error(`Recommendation failed: ${response.status}`);
}
const recommendations = await response.json();

This snippet illustrates the request shape; the variables are supplied by your application. The response uses a result wrapper with credit fields. Your interface reads recommendation options and resolves item product IDs against its catalog. Confirm the detailed result schema during onboarding.

Let the result guide the experience

Offer a clear empty state when no products match. Keep price and availability in sync with your catalog, and let customers revise their preferences. To visualize a chosen outfit, supply its garment images to the Virtual Try-On API.

PREVIOUSVirtual Try-On

NEXTErrors & troubleshooting