Analysis

Analyze a photo

Send one or more images and receive structured AI analysis. Pick a curated stack for a domain-specific workflow, compose your own custom stack from individual lenses, or augment a curated stack with extra lenses.

Image input

Provide a single image via imageUrl or imageBase64, or multiple images via the images array (max 50). Do not mix single and multi-image inputs.

Stack and lens selection

  • preset: pick a curated stack by name (e.g. full-analysis, vehicle-condition). The field is named preset on the wire for back-compat; the concept is a stack.
  • modules: pass an explicit lens list to build a custom stack (overrides preset). The field is named modules on the wire for back-compat; the concept is lenses.
  • modulesAdd / modulesRemove: augment a curated stack with extra lenses, or strip a lens you do not need.

Delta billing

Repeat calls on the same image hit the per-user-per-photo lens projection. Already-analyzed lenses are served from the projection at zero cost; only newly-requested lenses are billed and sent to the LLM. Pass refresh: true to bypass the cache and re-bill every requested lens. A full cache hit returns meta.cacheHit: true and usage.creditsCharged: 0.

Test sandbox

Requests with a pt_test_ key return fixture data instantly. No AI call is made, no usage is billed. Use this for development and CI.

post/v1/analyze

Request

  • Base URL: https://api.phototology.com
  • URL: https://api.phototology.com/v1/analyze
  • Auth: HTTP bearer

Request body

imageUrlstring uri
imageBase64string
presetstring
modulesstring[]
modulesAddstring[]
modulesRemovestring[]
moduleOptionsobject
refreshboolean

Response

Analysis completed successfully. The output object contains module-specific results keyed by module name. On a registry cache hit, meta.cacheHit is true and usage.creditsCharged is 0.

Content safety block. Moderation runs on every photo before analysis. If an image is blocked, this endpoint still returns 200 (deliberately not a 4xx) with output.moderation.safe: false, a human-readable output.moderation.reason, meta.safetyBlockInfo, usage.creditsCharged: 0, and Cache-Control: no-store, private. Check output.moderation.safe before trusting any analysis fields. See the moderation-block example.

idstring required
object'analysis' required
livemodeboolean required
schemaVersionstring required
createdAtstring required
outputobject required
outputSchema'photo' | 'vehicle' required
warningsstring[] required
embeddingnumber[]

Changes

No recorded changes to this operation across all 1 revision of this API.