PhotoMentor API

The public API exposes the same structured critique contract used by PhotoMentor internally. Send one image as multipart form data and receive a machine-friendly response with a score, critique, strengths, weaknesses, and advice variants.

Base URL

https://api.photomentor.pro/api/v1

Auth

X-API-Key

Formats

JPEG, PNG, WebP, GIF

Authentication

Authentication uses a client-specific API key passed in the `X-API-Key` header. Access is provisioned manually.

X-API-Key: sk_live_your_client_key

How to get API access

API keys are issued manually. There is no public self-serve provisioning flow yet.

Contact team@photomentor.pro with your use case, expected request volume, and timeline.
We provision a client record, quotas, and a key alias for your integration.
You receive the raw API key once through a direct channel.
Your application sends that key in the `X-API-Key` header.

For security, PhotoMentor stores only a SHA-256 hash of the key, not the raw token itself.

Endpoint

POST https://api.photomentor.pro/api/v1/analyze

Request

Send multipart form data with one image and optional localization fields.

Field	Type	Required	Notes
image	file	Yes	JPEG, PNG, WebP, or GIF. Max 20 MB.
language	string	No	`en`, `ru`, `de`, `es`. Default: `en`.
tone_mode	string	No	`brutal` or `supportive`. Default: `brutal`.

Response shape

{
  "request_id": "9e3f7b62-2d4d-4b85-8b7a-...",
  "score": 7.2,
  "genre": "Street Photography",
  "verdict": "Strong timing, weak edge control.",
  "critique": "The frame has energy, but the right edge pulls attention...",
  "strengths": [
    "Clear subject separation",
    "Good timing"
  ],
  "weaknesses": [
    "Distracting right edge",
    "Flat light"
  ],
  "advice": {
    "purist": "Simplify the frame by stepping left.",
    "standard": "Recompose to clean the edge and lift separation.",
    "creative": "Keep the tension, but make it more intentional."
  },
  "visual_facts": "One person crossing a city street...",
  "mood": "restless"
}

Field	Type	Description
request_id	string	Unique identifier for support and tracing.
score	number	Overall 0–10 score with one decimal.
genre	string	Detected photography genre.
verdict	string	One-line summary judgment.
critique	string	Full written critique.
strengths	string[]	Structured positives list.
weaknesses	string[]	Structured negatives list.
advice	object	Three advice variants: `purist`, `standard`, `creative`.
visual_facts	string	Factual scene summary.
mood	string	Detected mood or atmosphere.

Error contract

Status	Meaning
200	Successful analysis.
401	Missing or invalid API key.
413	Image exceeds 20 MB.
422	Unsupported or invalid image.
429	Rate limit exceeded.
500	Analysis failed. Retry later.

Examples

cURL

curl -X POST "https://api.photomentor.pro/api/v1/analyze" \
  -H "X-API-Key: sk_live_your_client_key" \
  -F "image=@photo.jpg" \
  -F "language=en" \
  -F "tone_mode=brutal"

Python

import requests

with open("photo.jpg", "rb") as f:
    response = requests.post(
        "https://api.photomentor.pro/api/v1/analyze",
        headers={"X-API-Key": "sk_live_your_client_key"},
        files={"image": ("photo.jpg", f, "image/jpeg")},
        data={"language": "en", "tone_mode": "supportive"},
        timeout=60,
    )

response.raise_for_status()
data = response.json()

JavaScript

const form = new FormData();
form.append("image", fileInput.files[0]);
form.append("language", "en");
form.append("tone_mode", "brutal");

const response = await fetch("https://api.photomentor.pro/api/v1/analyze", {
  method: "POST",
  headers: {
    "X-API-Key": "sk_live_your_client_key"
  },
  body: form
});

if (!response.ok) {
  throw new Error(`API error ${response.status}`);
}

const data = await response.json();

Rate limits and provisioning

Each client key has its own hourly and daily quota. There is also an IP-level abuse brake to protect the service from generic flooding. Access is currently provisioned manually rather than self-serve.

If you need access, contact us with your use case, expected volume, and integration timeline.

Customization and mentor profiles

Some API deployments can be provisioned with a custom mentor profile. This is intended for schools, contests, or branded review programs that want critique aligned to a named instructor or internal methodology.

Custom mentor behavior is configured per client, not passed as a public request field in `v1`.
Customization can affect critique tone, vocabulary, emphasis, and instructional priorities.
Selected deployments may also include voice delivery for a configured mentor profile.
This is handled during provisioning and rollout, not through self-serve API setup.

If you need this path, mention it in your access request so it can be scoped explicitly.

Changelog and artifacts

Download OpenAPI Release Notes