{"openapi":"3.1.0","info":{"title":"LookKind Connector API","version":"2.1.0","description":"An adult visual style consultation. The API creates one recommendation shown from front, left, and right, then revises all three views and the practical plan through an ongoing dialogue."},"servers":[{"url":"https://www.lookkind.com"}],"paths":{"/api/checkout":{"post":{"operationId":"createLookKindCheckout","summary":"Create a $99 one-time Stripe Checkout session","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"string","enum":["hair","makeup","both"],"default":"both"}}}}}},"responses":{"200":{"description":"Checkout created"},"429":{"description":"Hourly checkout request limit reached"},"503":{"description":"Payments or usage protection are not configured"}}}},"/api/v1/style-plan":{"post":{"operationId":"createLookKindConsultation","summary":"Create one opening recommendation from three adult portrait views","description":"Returns one coherent look in three identity-preserving portraits (front, left, right), explanation, routine, and focused product kit. Use style-dialogue to revise all three views together.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["left_image","front_image","right_image","goal","age_confirmed","checkout_session_id"],"properties":{"left_image":{"type":"string","format":"binary","description":"Left-profile JPG, PNG, or WebP, maximum 10 MB."},"front_image":{"type":"string","format":"binary","description":"Front-facing JPG, PNG, or WebP, maximum 10 MB."},"right_image":{"type":"string","format":"binary","description":"Right-profile JPG, PNG, or WebP, maximum 10 MB."},"goal":{"type":"string","enum":["hair","makeup","both"]},"notes":{"type":"string","maxLength":500,"description":"Optional maintenance, workplace, length, color, grooming, or makeup preferences."},"age_confirmed":{"type":"boolean","description":"True only when the subject is 18+ and consented."},"checkout_session_id":{"type":"string","description":"Verified Stripe Checkout Session ID for the LookKind consultation."}}}}}},"responses":{"200":{"description":"Opening consultation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Consultation"}}}},"400":{"description":"Invalid request, age confirmation, or consent"},"402":{"description":"Payment required or not verified"},"413":{"description":"Image exceeds 10 MB"},"415":{"description":"Unsupported image type"},"429":{"description":"Hourly request limit or included consultation limit reached"},"502":{"description":"Generation provider failure; the paid session may be retried"}}}},"/api/v1/style-dialogue":{"post":{"operationId":"reviseLookKindConsultation","summary":"Revise the current portrait and plan from a dialogue message","description":"Preserves the original identity references and unrequested choices while applying the latest user request to the visual, explanation, routine, and products together.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["left_image","front_image","right_image","current_image","user_message","current_recommendation","age_confirmed","checkout_session_id"],"properties":{"left_image":{"type":"string","format":"binary","description":"Left-profile JPG, PNG, or WebP, maximum 10 MB."},"front_image":{"type":"string","format":"binary","description":"Front-facing JPG, PNG, or WebP, maximum 10 MB."},"right_image":{"type":"string","format":"binary","description":"Right-profile JPG, PNG, or WebP, maximum 10 MB."},"current_image":{"type":"string","format":"binary","description":"The latest generated LookKind portrait."},"analysis_image":{"type":"string","format":"binary","description":"The immutable analysis portrait returned by style-plan. Send the SAME image with every revision to lock framing and preserve the unretouched comparison. Legacy clients without it use current_image as their reference."},"left_current_image":{"type":"string","format":"binary","description":"The latest accepted projected_views.left image, for side-view continuity."},"right_current_image":{"type":"string","format":"binary","description":"The latest accepted projected_views.right image, for side-view continuity."},"left_composition_image":{"type":"string","format":"binary","description":"The FIRST accepted projected_views.left image. Reuse it unchanged to keep left-view framing fixed across revisions."},"right_composition_image":{"type":"string","format":"binary","description":"The FIRST accepted projected_views.right image. Reuse it unchanged to keep right-view framing fixed across revisions."},"user_message":{"type":"string","maxLength":500,"description":"The next change requested in the style dialogue."},"history":{"type":"string","description":"JSON array containing up to ten recent user/assistant messages."},"current_recommendation":{"type":"string","description":"JSON object describing the current title, summary, steps, focus areas, and revision."},"goal":{"type":"string","enum":["hair","makeup","both"]},"notes":{"type":"string","maxLength":500},"age_confirmed":{"type":"boolean"},"checkout_session_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Revised recommendation created","content":{"application/json":{"schema":{"type":"object","required":["recommendation","note"],"properties":{"recommendation":{"$ref":"#/components/schemas/Recommendation"},"note":{"type":"string"}}}}}},"400":{"description":"Invalid message, images, age confirmation, or consent"},"402":{"description":"Payment required or not verified"},"409":{"description":"Opening plan required or another generation is already running"},"429":{"description":"Hourly request limit or 10-revision consultation limit reached"},"502":{"description":"Revision provider failure; the prior revision remains valid"}}}}},"components":{"schemas":{"Consultation":{"type":"object","required":["consultation_id","created_at","recommendation","note"],"properties":{"consultation_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"recommendation":{"$ref":"#/components/schemas/Recommendation"},"note":{"type":"string"}}},"Recommendation":{"type":"object","required":["title","summary","assistant_message","image_data_url","steps","products","focus_areas","revision"],"properties":{"title":{"type":"string"},"summary":{"type":"string"},"assistant_message":{"type":"string"},"analysis_image_data_url":{"type":["string","null"],"description":"Standardized baseline portrait using the same framing, lighting, and studio background as the projected result."},"image_data_url":{"type":["string","null"],"description":"The front projected portrait, also present as projected_views.front. Base64 JPEG data URL. Null only in a clearly labeled local demo without generation."},"projected_views":{"type":"object","additionalProperties":false,"required":["front","left","right"],"description":"Three generated angles of the SAME look and revision, using each original upload as its angle reference. Present on newly generated real results; omitted on legacy/demo results. Never substitute one angle for another. Each revision replaces the complete set together.","properties":{"front":{"type":"string","description":"Front-view JPEG data URL, identical to image_data_url."},"left":{"type":"string","description":"Left-view JPEG data URL matching the side shown in left_image."},"right":{"type":"string","description":"Right-view JPEG data URL matching the side shown in right_image."}}},"revision":{"type":"integer","minimum":1},"steps":{"type":"array","minItems":4,"maxItems":6,"items":{"type":"string"}},"focus_areas":{"type":"array","minItems":3,"maxItems":3,"items":{"$ref":"#/components/schemas/FocusArea"}},"products":{"type":"array","minItems":3,"maxItems":3,"items":{"$ref":"#/components/schemas/Product"}}}},"FocusArea":{"type":"object","required":["label","description","observation","impact","projected_change","action","x","y","side"],"properties":{"label":{"type":"string"},"description":{"type":"string"},"observation":{"type":"string","description":"Direct, non-diagnostic description of what is visibly supported by the source photos."},"impact":{"type":"string","description":"Why the visible feature matters to the portrait presentation."},"projected_change":{"type":"string","description":"What the generated projection changes using presentation choices or an explicitly requested hypothetical cosmetic preview."},"action":{"type":"string","description":"Practical next action; not medical advice."},"follow_up_prompt":{"type":"string","maxLength":120,"description":"Personalized conversation starter based on this area’s observation and proposed change. Show only before the first user message; omit for legacy or demo results without a generated prompt."},"target_feature":{"type":"string","enum":["lips","nose","brows","eyes","under_eyes","cheeks","skin","forehead","chin","jawline","beard","hair"],"description":"Anatomical feature discussed by the recommendation. Locate it with facial landmarks on analysis_image_data_url; x/y are legacy estimates, not authoritative marker positions."},"target_side":{"type":"string","enum":["left","center","right"],"description":"Feature side in displayed-image coordinates, independent of the callout placement side."},"x":{"type":"number","minimum":8,"maximum":92,"description":"Horizontal marker position as a percentage of the standardized analysis portrait."},"y":{"type":"number","minimum":8,"maximum":92,"description":"Vertical marker position as a percentage of the standardized analysis portrait."},"side":{"type":"string","enum":["left","right"],"description":"Preferred side for the visual callout."}}},"Product":{"type":"object","required":["brand","name","purpose","retailer","price","product_url","image_url"],"properties":{"brand":{"type":"string"},"name":{"type":"string"},"purpose":{"type":"string"},"retailer":{"type":"string"},"price":{"type":"string"},"product_url":{"type":"string","format":"uri"},"image_url":{"type":"string","format":"uri"}}}}}}