{"openapi":"3.1.0","info":{"title":"Vision API (Moondream)","description":"Send a prompt plus one or more images (base64 JSON or file upload) and get a text reply from `moondream` via Ollama. Up to 16 images per request (hard cap 32). Moondream does not support the `think` flag (ignored for this model). **Face workflow:** `POST /v1/face/compare` — 1 reference + up to 10 candidates. Human-readable guide: [`GET /instructions`](/instructions). Interactive API: [`GET /scalar`](/scalar).","version":"1.3.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/vision":{"post":{"summary":"Vision Json","description":"JSON endpoint — send one or more base64 images + a prompt.\n\nAccepts either ``images_base64`` (list, preferred) or ``image_base64``\n(single string, kept for backward compatibility). Each entry may be a\nbare base64 string or a ``data:image/...;base64,...`` URL.","operationId":"vision_json_v1_vision_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisionJSONRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vision/upload":{"post":{"summary":"Vision Upload","description":"Multipart endpoint — upload one or more raw image files + a prompt.\n\nSend multiple files by repeating the ``images`` form field.","operationId":"vision_upload_v1_vision_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_vision_upload_v1_vision_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/face/compare":{"post":{"summary":"Face Compare Json","description":"Compare one **reference** image against **1–10 candidates** (pairwise).\n\nThe server runs one Ollama call per candidate: `[reference, candidate_i]`\nwith a fixed instruction prompt that asks for ``YES`` / ``NO`` on line 1.\n\n**Limitation:** this uses a vision-language model (e.g. Moondream). It is\n**not** a certified face matcher — use the returned ``match_label`` only as\na soft signal. See ``GET /instructions`` for details and examples.","operationId":"face_compare_json_v1_face_compare_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaceCompareJSONRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaceCompareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/face/compare/upload":{"post":{"summary":"Face Compare Upload","description":"Multipart **reference + candidates** upload (same logic as ``POST /v1/face/compare``).","operationId":"face_compare_upload_v1_face_compare_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_face_compare_upload_v1_face_compare_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaceCompareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/info":{"get":{"summary":"Info","description":"Machine-readable index of the API (the JSON version of the root page).","operationId":"info_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Body_face_compare_upload_v1_face_compare_upload_post":{"properties":{"reference":{"type":"string","contentMediaType":"application/octet-stream","title":"Reference","description":"Single reference photo of the person to match."},"candidates":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Candidates","description":"1–10 candidate images (repeat the `candidates` field for each file)."},"max_tokens":{"type":"integer","title":"Max Tokens","default":120},"think":{"type":"boolean","title":"Think","default":false},"temperature":{"type":"number","title":"Temperature","default":0.5},"top_p":{"type":"number","title":"Top P","default":0.95},"top_k":{"type":"integer","title":"Top K","default":64}},"type":"object","required":["reference","candidates"],"title":"Body_face_compare_upload_v1_face_compare_upload_post"},"Body_vision_upload_v1_vision_upload_post":{"properties":{"prompt":{"type":"string","title":"Prompt","description":"Instruction/question about the image(s)"},"images":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Images","description":"One or more PNG/JPEG/WebP files (up to 16)"},"max_tokens":{"type":"integer","title":"Max Tokens","default":500},"think":{"type":"boolean","title":"Think","default":false},"temperature":{"type":"number","title":"Temperature","default":1.0},"top_p":{"type":"number","title":"Top P","default":0.95},"top_k":{"type":"integer","title":"Top K","default":64}},"type":"object","required":["prompt","images"],"title":"Body_vision_upload_v1_vision_upload_post"},"CandidateCompareRow":{"properties":{"index":{"type":"integer","title":"Index","description":"Index into candidate_images_base64 (0-based)."},"match_label":{"type":"string","title":"Match Label","description":"yes | no | unclear — parsed from the model's first output line (heuristic, not biometric proof)."},"raw_reply":{"type":"string","title":"Raw Reply","description":"Full model text for this candidate."},"prompt_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Tokens"},"completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Completion Tokens"},"timings_ms":{"additionalProperties":true,"type":"object","title":"Timings Ms"}},"type":"object","required":["index","match_label","raw_reply"],"title":"CandidateCompareRow"},"FaceCompareJSONRequest":{"properties":{"reference_image_base64":{"type":"string","title":"Reference Image Base64","description":"Reference individual — raw base64 or data URL (PNG/JPEG/WebP)."},"candidate_images_base64":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Candidate Images Base64","description":"Between 1 and 10 candidate images (same encoding rules as /v1/vision)."},"max_tokens":{"type":"integer","maximum":500.0,"minimum":20.0,"title":"Max Tokens","description":"Token budget for each pairwise comparison (keep short).","default":120},"think":{"type":"boolean","title":"Think","description":"Gemma-only internal reasoning. Ignored for Moondream.","default":false},"temperature":{"type":"number","maximum":2.0,"minimum":0.0,"title":"Temperature","default":0.5},"top_p":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Top P","default":0.95},"top_k":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Top K","default":64}},"type":"object","required":["reference_image_base64","candidate_images_base64"],"title":"FaceCompareJSONRequest","description":"Compare one reference photo against up to 10 candidate photos (one model call per candidate).","examples":[{"candidate_images_base64":["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="],"max_tokens":120,"reference_image_base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=","temperature":0.5,"think":false}]},"FaceCompareResponse":{"properties":{"model":{"type":"string","title":"Model"},"candidate_count":{"type":"integer","title":"Candidate Count"},"disclaimer":{"type":"string","title":"Disclaimer","default":"Vision-language models are not biometric systems. Treat match_label as a weak heuristic for triage only — not legal or security-grade identity proof."},"candidates":{"items":{"$ref":"#/components/schemas/CandidateCompareRow"},"type":"array","title":"Candidates"},"aggregate_timings_ms":{"additionalProperties":true,"type":"object","title":"Aggregate Timings Ms","description":"Sum of per-candidate timings_ms fields (load, prompt_eval, generation, total)."}},"type":"object","required":["model","candidate_count","candidates"],"title":"FaceCompareResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VisionJSONRequest":{"properties":{"prompt":{"type":"string","title":"Prompt","description":"Instruction/question about the image(s)"},"images_base64":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Images Base64","description":"List of raw base64 strings or data URLs (data:image/png;base64,...). Up to 16 images per request."},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"[Deprecated] Single-image shortcut. Prefer 'images_base64'."},"max_tokens":{"type":"integer","maximum":8000.0,"minimum":1.0,"title":"Max Tokens","default":500},"think":{"type":"boolean","title":"Think","description":"Gemma-only: internal reasoning. Ignored for Moondream.","default":false},"temperature":{"type":"number","maximum":2.0,"minimum":0.0,"title":"Temperature","default":1.0},"top_p":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Top P","default":0.95},"top_k":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Top K","default":64},"stream":{"type":"boolean","title":"Stream","description":"Stream partial tokens as Server-Sent-Events","default":false}},"type":"object","required":["prompt"],"title":"VisionJSONRequest"}}}}