Food photo in.
Nutrition out.

Keys

Your keys live on your dashboard. Your first purchase comes with a test key: ns_test_… returns a fixed sample result for free, so you can build your integration first. Create ns_live_… keys there for real scans; they use your credits. Both stop when your credits run out. Send the key as a bearer token.

Call the API from your server. A key inside a mobile app can be pulled out of the binary and used by anyone.

Authorization: Bearer ns_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create a scan

POST /scans waits for the result and returns it in the same response. Send image_base64 or image_url for meal and label, and text for text.

curl "$NUTRISCAN_API_URL/scans" \
  -H "Authorization: Bearer $NUTRISCAN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1c5e0a-order-4411" \
  -d '{
    "type": "meal",
    "image_url": "https://example.com/lunch.jpg",
    "language": "en",
    "context": { "meal_time": "lunch", "cooking_method": ["grilled"] }
  }'

Send an Idempotency-Key header to retry safely. The same key with the same body returns the first result and uses credits once. If that first try failed (402, 500), the same key runs a fresh scan. A scan can take up to 95 seconds, so set your client timeout to at least 100, or use streaming.

Streaming

A big plate takes a minute. Add "stream": true and the same call answers at once with text/event-stream: the items the photo shows arrive after about 10 to 15 seconds, the full result when it is ready. Show the items to your user while the numbers load.

curl -N "$NUTRISCAN_API_URL/scans" \
  -H "Authorization: Bearer $NUTRISCAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "meal", "image_url": "https://example.com/lunch.jpg", "stream": true }'

event: scan.started
data: {"id":"scn_8Kd2…","status":"processing"}

event: items.detected
data: {"id":"scn_8Kd2…","dish_name":"Tofu salad bowl","items":[{"name":"Tofu","portion":"100 g"}, …]}

: ping

event: scan.completed
data: { …the same JSON as a normal response… }

Errors found before the scan starts (a bad key, a bad body, the rate limit, no credits) come back as a normal JSON error with their status code, not as a stream. A streamed scan can run up to 140 seconds. It uses the same credits as a normal call.

The result

Units are in the field names. Each item says where its numbers came from: food_db (our food database), web or estimate.

{
  "id": "scn_Q2mX8rT4vK1pLw9eZb3nYh6A",
  "status": "succeeded",
  "engine_version": "2026.11.0",
  "language": "en",
  "meal": {
    "name": "Grilled chicken with rice and salad",
    "nutri_score": "B",
    "nutri_score_reason": "Lean protein and vegetables balance the rice; moderate sodium from the marinade.",
    "totals": {
      "calories": 515, "protein_g": 51.9, "carbs_g": 47.7, "fat_g": 11.1,
      "fiber_g": 2.2, "sugar_g": 1.6, "saturated_fat_g": 2.3, "trans_fat_g": 0,
      "micros": { "sodium_mg": 457, "potassium_mg": 645, "calcium_mg": 69, "iron_mg": 4.2,
                  "vitamin_c_mg": 14, "vitamin_a_mcg": 204, "omega_3_mg": 100, "…": "13 in all" }
    }
  },
  "items": [
    {
      "name": "Grilled chicken breast",
      "portion": { "value": 150, "unit": "g", "display": "150 g" },
      "grams": 150,
      "calories": 248, "protein_g": 46.5, "carbs_g": 0, "fat_g": 5.4,
      "micros": { "sodium_mg": 410, "…": "…" },
      "source": "food_db"
    }
  ]
}

A live result also has "credits_used": 64 and ends with "usage": {"credits_left": 30760}. Test keys return the same shape with "test_mode": true and "credits_used": 0.

Other endpoints

Errors

Every error has the same body: {"error": {"code": "insufficient_credits", "message": "…"}}. Branch on code; the message is for people.

Limits

Your data

We keep the photos and results you send and use them to improve our food database. Do not send photos of people or anything that identifies your users. Results are not medical advice.