Recipe

A cooking recipe extracted from a video. Field names and semantics are modeled after schema.org/Recipe; ISO 8601 Durations are replaced with whole-minute integers and a few video-extraction extras are added (videoTimestamp on steps, tips, sourceQuote, difficulty). Optional fields are omitted when the creator does not state them — do not infer.

Fields

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "vidextract.predefined.recipe.v1",
  "title": "Recipe",
  "description": "A cooking recipe extracted from a video. Field names and semantics are modeled after schema.org/Recipe; ISO 8601 Durations are replaced with whole-minute integers and a few video-extraction extras are added (videoTimestamp on steps, tips, sourceQuote, difficulty). Optional fields are omitted when the creator does not state them — do not infer.",
  "type": "object",
  "required": [
    "name",
    "ingredients",
    "instructions"
  ],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the dish."
    },
    "description": {
      "type": "string",
      "description": "One or two sentences describing the finished dish."
    },
    "cuisine": {
      "type": "string",
      "description": "Cuisine of origin, lowercased — e.g. 'italian', 'thai', 'mexican', 'fusion'. Schema.org recipeCuisine."
    },
    "category": {
      "type": "string",
      "description": "Type of dish, lowercased — e.g. 'dessert', 'main course', 'appetizer', 'snack', 'breakfast'. Schema.org recipeCategory."
    },
    "yield": {
      "type": "object",
      "description": "How many portions the recipe produces. Schema.org recipeYield.",
      "required": [
        "amount"
      ],
      "additionalProperties": false,
      "properties": {
        "amount": {
          "type": "number",
          "description": "Numeric portion count."
        },
        "unit": {
          "type": "string",
          "description": "Portion unit — e.g. 'servings', 'pieces', 'loaves'. Defaults to 'servings' if the creator doesn't specify."
        }
      }
    },
    "prepTimeMinutes": {
      "type": "integer",
      "description": "Prep time (knife work, mixing — anything before heat is applied) in whole minutes. Omit if not stated. Schema.org prepTime in minutes instead of ISO 8601."
    },
    "cookTimeMinutes": {
      "type": "integer",
      "description": "Active cook time in whole minutes. Omit if not stated. Schema.org cookTime in minutes instead of ISO 8601."
    },
    "totalTimeMinutes": {
      "type": "integer",
      "description": "Total time from start to finished dish in whole minutes. Omit if not stated. Schema.org totalTime in minutes instead of ISO 8601."
    },
    "difficulty": {
      "type": "string",
      "enum": [
        "easy",
        "medium",
        "hard"
      ],
      "description": "Subjective difficulty if explicitly stated by the creator. Omit otherwise — do not infer."
    },
    "dietaryTags": {
      "type": "array",
      "description": "Diet labels that apply to the finished dish, normalized to lowercase kebab-case. Mirrors schema.org suitableForDiet.",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "vegan",
          "vegetarian",
          "pescatarian",
          "gluten-free",
          "dairy-free",
          "keto",
          "paleo",
          "low-carb",
          "low-fat",
          "low-sodium",
          "halal",
          "kosher",
          "nut-free",
          "egg-free"
        ]
      }
    },
    "tools": {
      "type": "array",
      "description": "Equipment required to follow the recipe. Schema.org tool. Skip optional substitutes (e.g. 'or a fork') unless they're the only option shown.",
      "items": {
        "type": "string"
      }
    },
    "ingredients": {
      "type": "array",
      "description": "Ingredients required. Each ingredient is parsed into quantity + unit + item rather than a free-form string. Schema.org recipeIngredient.",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "item"
        ],
        "additionalProperties": false,
        "properties": {
          "quantity": {
            "type": "string",
            "description": "Amount as a string so fractions ('1/2', '1 1/4') and decimals ('0.5') round-trip cleanly. Omit when not specified ('a pinch', 'to taste')."
          },
          "unit": {
            "type": "string",
            "description": "Unit of measure — e.g. 'g', 'tbsp', 'tsp', 'cup', 'ml', 'oz', 'whole'. Omit for unit-less items like '2 eggs'."
          },
          "item": {
            "type": "string",
            "description": "The ingredient itself, lower-cased and singular where idiomatic ('clove garlic', not 'cloves garlic'). Include qualifiers that affect the shopping list ('Greek yogurt', 'kosher salt')."
          },
          "preparation": {
            "type": "string",
            "description": "Prep state if specified — e.g. 'minced', 'roughly chopped', 'room temperature', 'softened'. Omit if not stated."
          },
          "optional": {
            "type": "boolean",
            "description": "True if the source explicitly calls the ingredient optional, 'to taste', or 'for garnish'.",
            "default": false
          }
        }
      }
    },
    "instructions": {
      "type": "array",
      "description": "Ordered preparation steps. Group implicitly-related actions into one step; split when the creator pauses, changes pan, or moves to a different component. Schema.org recipeInstructions (HowToStep).",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "text"
        ],
        "additionalProperties": false,
        "properties": {
          "text": {
            "type": "string",
            "description": "Imperative instruction — e.g. 'Whisk eggs and sugar until pale and doubled in volume.' Use active verbs, not narration."
          },
          "durationMinutes": {
            "type": "integer",
            "description": "How long this step takes in whole minutes, if the creator states it ('let rise for 45 minutes'). Omit otherwise — do not infer."
          },
          "videoTimestamp": {
            "type": "string",
            "description": "Start timestamp of this step in the source video, formatted 'mm:ss' or 'h:mm:ss'. Omit if unknown. Vidextract extension, not part of schema.org.",
            "pattern": "^(\\d{1,2}:)?\\d{1,2}:\\d{2}$"
          }
        }
      }
    },
    "tips": {
      "type": "array",
      "description": "Substitutions, storage advice, doneness cues, or pro tips the creator mentions outside the main instruction flow. Vidextract extension.",
      "items": {
        "type": "string"
      }
    },
    "sourceQuote": {
      "type": "string",
      "description": "If the creator credits an external source ('my grandmother's recipe', 'adapted from Bon Appétit'), capture the phrase verbatim. Omit otherwise. Vidextract extension."
    }
  }
}

Use it via the API

Pass schemaId: "vidextract.predefined.recipe.v1" when you submit an extraction. The call returns an id immediately. Poll GET /v1/extractions/{id}/result (or register a webhook) for the structured result.

curl -s -X POST https://postreef.com/v1/extractions \
  -H "x-api-key: $VIDEXTRACT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
       "inputs": ["transcript", "comments"],
       "schemaId": "vidextract.predefined.recipe.v1"}'

Full request/response shape in the API reference; copy-paste poll loops in the API quickstart.