openapi: 3.0.3
info:
  title: fatsecret Image Recognition API
  description: >-
    The fatsecret Image Recognition method accepts a Base64-encoded photograph of one or more foods
    and returns the identified food items, their suggested servings, and the nutritional content
    eaten, matched against fatsecret's verified nutrition database for the requested region and
    language. Built on top of large language models and launched in late 2024, it replaced ten years
    of in-house computer vision work.
  version: '2.0'
  contact:
    name: fatsecret Platform
    url: https://platform.fatsecret.com/platform-api
  x-provenance:
    generated: '2026-08-12'
    method: generated
    source: https://platform.fatsecret.com/docs/v2/image.recognition
    note: >-
      Authored from fatsecret's own published method documentation, which specifies the HTTP verb,
      endpoint, every request parameter and the response fields. fatsecret publishes no
      machine-readable contract for this method; nothing here is inferred beyond what that page
      states.
servers:
- url: https://platform.fatsecret.com/rest
  description: REST endpoint for URL-based and method-based integration
security:
- oauth2: []
- oauth1: []
tags:
- name: Image Recognition
  description: Identify foods and their nutrition from a photograph
paths:
  /image-recognition/v2:
    post:
      tags:
      - Image Recognition
      summary: Recognize foods in an image
      description: >-
        Accepts a Base64-encoded image of one or more foods and returns the identified foods with
        suggested servings and the nutritional content eaten.
      operationId: recognizeFoodsInImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageRecognitionRequest'
      responses:
        '200':
          description: Foods identified in the image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodResponse'
        '400':
          description: Invalid request — see the fatsecret error code catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or expired token (error code 13) or invalid signature (error code 8)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (error code 14) or invalid IP address detected (error code 21)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Application request limit reached (error code 11)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ImageRecognitionRequest:
      type: object
      required:
      - image_b64
      properties:
        image_b64:
          type: string
          format: byte
          maxLength: 999982
          description: A Base64 image of one or more foods. Limited to 999,982 characters.
        include_food_data:
          type: boolean
          description: Include full food data inline in the response.
        eaten_foods:
          type: array
          description: Previously consumed foods, provided to assist with more accurate matching.
          items:
            $ref: '#/components/schemas/EatenFood'
        region:
          type: string
          description: Filter results by region.
          example: US
        language:
          type: string
          description: Return results in the specified language. Only used when region is specified.
          example: en
    EatenFood:
      type: object
      required:
      - food_id
      - food_name
      properties:
        food_id:
          type: integer
          format: int64
        food_name:
          type: string
        food_brand:
          type: string
        serving_description:
          type: string
        serving_size:
          type: string
    FoodResponse:
      type: object
      properties:
        food_response:
          type: array
          items:
            $ref: '#/components/schemas/RecognizedFood'
    RecognizedFood:
      type: object
      properties:
        food_id:
          type: integer
          format: int64
        food_entry_name:
          type: string
        eaten:
          type: object
          description: Nutritional content of the portion identified.
          properties:
            total_nutritional_content:
              type: object
        suggested_serving:
          type: object
          description: Serving fatsecret suggests for the identified portion.
        food:
          type: object
          description: Complete food record, returned when include_food_data is true.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: fatsecret error code — see errors/fatsecret-error-codes.yml
            message:
              type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://oauth.fatsecret.com/connect/token
          scopes:
            basic: Basic access to food and recipe data
            premier: Premier access including image recognition and NLP
    oauth1:
      type: http
      scheme: oauth
      description: OAuth 1.0a request signing