MacroEstimator
Dashboard

Estimate Endpoint

Get AI-powered nutrition estimates from text descriptions or images.

Endpoints

POST/v1/estimate

Streaming endpoint - returns results via Server-Sent Events (SSE)

POST/v1/estimate/sync

Non-streaming endpoint - returns complete JSON response

Request Body

ParameterTypeRequiredDescription
messagesarrayYesArray of message objects describing the food

Message Format

Messages follow the OpenAI chat format. Each message has a role and content.

Text-only message

{
  "role": "user",
  "content": "2 scrambled eggs with toast"
}

Message with image

{
  "role": "user",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://api.macroestimator.com/images/abc123.jpg"
      }
    },
    {
      "type": "text",
      "text": "What are the macros for this meal?"
    }
  ]
}

Examples

Basic text estimation

curl -X POST https://api.macroestimator.com/v1/estimate/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "1 cup of oatmeal with a banana and honey"
      }
    ]
  }'

Streaming response

curl -X POST https://api.macroestimator.com/v1/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "grilled chicken salad"
      }
    ]
  }'

Response

Sync endpoint responsejson
{
  "items": [
    {
      "name": "Oatmeal",
      "quantity": 1,
      "unit": "cup cooked",
      "calories": 166,
      "protein": 6,
      "carbs": 28,
      "fat": 4
    },
    {
      "name": "Banana",
      "quantity": 1,
      "unit": "medium",
      "calories": 105,
      "protein": 1,
      "carbs": 27,
      "fat": 0
    },
    {
      "name": "Honey",
      "quantity": 1,
      "unit": "tablespoon",
      "calories": 64,
      "protein": 0,
      "carbs": 17,
      "fat": 0
    }
  ],
  "totals": {
    "calories": 335,
    "protein": 7,
    "carbs": 72,
    "fat": 4
  }
}

Uploading Images

Before using images in estimates, you need to upload them using the upload endpoint.

Upload a base64 image
curl -X POST https://api.macroestimator.com/v1/upload/base64 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD..."
  }'
Upload responsejson
{
  "url": "https://api.macroestimator.com/images/abc123.jpg"
}

Error Responses

400Bad Request

Invalid request body or missing required fields

401Unauthorized

Missing or invalid API key

429Too Many Requests

Rate limit exceeded - check Retry-After header