API DocsAPI Docs / Ai / Meal Estimations

POST /api/v1/ai/meal-estimations

Estimates the nutritional content of a meal from a single photograph, returning machine-readable macros in the shape POST /api/v1/tracker/meals accepts without transformation.

The photo is sent to the model as an inline base64 data: URI and discarded with the request — it is not stored, not attached to a meal, and never written to a log. Nothing about the estimate is logged either, beyond the caller's id, the model, the token counts and the cost.

Permissions

No permission is required beyond authentication. The call is metered against the caller's own rolling 24-hour AI spend budget, exactly as an AI chat message is — see AI usage limits.

Request Body Parameters

The request must be sent as multipart/form-data. One image per call — this endpoint does not accept a list, and it does not accept PDFs.

Request Example

POST /api/v1/ai/meal-estimations
Content-Type: multipart/form-data

image=@meal.jpg

Response

200 OK

{
  "data": {
    "description": "Grilled chicken breast, white rice, and a side salad",
    "calories": 620,
    "protein": 52,
    "carb": 61,
    "fat": 14,
    "confidence": "medium",
    "advisory": true
  }
}

The four numbers carry the same names and the same integer type as the nullable columns on tracker_meals, so the object can be handed to the meal form unchanged.

Any of the four may be null, and a null is a real answer. A figure the model could not judge is returned as null rather than as a guess or a zero — a photo that is not food comes back with all four null and a description saying so, never with fabricated numbers.

Macros are checked against the calories by the same invariant the meal-writing AI tool enforces (protein and carbohydrate at 4 kcal/g, fat at 9 kcal/g, within a tolerance). An answer that contradicts itself is asked for once more; if the second answer contradicts itself too, calories is returned as null rather than passed on. calories is the field that goes because it is the one derivable from the other three.

Error Responses

Two distinct 429s. The budget refusal is decided per user over a rolling 24-hour window; the rate limit is throttle:10,1 and is decided per minute. This endpoint is throttled harder than the chat endpoint's 30,1 because every call is a paid vision completion.

Metering

A successful call writes one ai_usage_events row (feature = meal_photo_estimate) carrying the served model, the token counts and the USD cost. That table is summed alongside ai_thread_messages when the budget is checked, so a meal estimate and an AI chat message draw on the same daily allowance. A retried estimate is billed twice, because it is two completions.