How-To

A tutorial or how-to extracted from a video — anything procedural that isn't a cooking recipe (DIY, software, repairs, crafts, setup guides). Modeled loosely on schema.org/HowTo. Steps are ordered and imperative; optional fields are omitted when not stated.

Fields

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "vidextract.predefined.howto.v1",
  "title": "How-To",
  "description": "A tutorial or how-to extracted from a video — anything procedural that isn't a cooking recipe (DIY, software, repairs, crafts, setup guides). Modeled loosely on schema.org/HowTo. Steps are ordered and imperative; optional fields are omitted when not stated.",
  "type": "object",
  "required": [
    "title",
    "steps"
  ],
  "additionalProperties": false,
  "properties": {
    "title": {
      "type": "string",
      "description": "What the tutorial teaches, phrased as the goal — e.g. 'How to replace a bike inner tube'."
    },
    "summary": {
      "type": "string",
      "description": "One or two sentences describing the end result and approach."
    },
    "category": {
      "type": "string",
      "description": "Domain, lowercased — e.g. 'diy', 'software', 'photography', 'gardening', 'car repair'."
    },
    "difficulty": {
      "type": "string",
      "enum": [
        "beginner",
        "intermediate",
        "advanced"
      ],
      "description": "Difficulty if stated or clearly implied by the creator. Omit if unsure."
    },
    "totalTimeMinutes": {
      "type": "integer",
      "description": "Total time to complete in whole minutes, if stated. Omit otherwise."
    },
    "estimatedCost": {
      "type": "string",
      "description": "Cost of materials if mentioned, as stated, e.g. 'under $20'. Omit otherwise."
    },
    "tools": {
      "type": "array",
      "description": "Tools required, lowercased. e.g. 'phillips screwdriver', 'tire levers'.",
      "items": {
        "type": "string"
      }
    },
    "materials": {
      "type": "array",
      "description": "Consumable materials or supplies needed (distinct from reusable tools).",
      "items": {
        "type": "string"
      }
    },
    "prerequisites": {
      "type": "array",
      "description": "Skills, accounts, or conditions assumed before starting. Short phrases. Omit if none.",
      "items": {
        "type": "string"
      }
    },
    "steps": {
      "type": "array",
      "description": "Ordered steps. Each is one discrete action. Split when the creator moves to a new phase.",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "text"
        ],
        "additionalProperties": false,
        "properties": {
          "text": {
            "type": "string",
            "description": "Imperative instruction, e.g. 'Loosen the valve cap and fully deflate the tube.'"
          },
          "detail": {
            "type": "string",
            "description": "Extra clarifying detail for the step if the creator elaborates. Omit if the text is self-contained."
          },
          "warning": {
            "type": "string",
            "description": "Safety warning or common-mistake caution tied to this step. Omit if none."
          },
          "videoTimestamp": {
            "type": "string",
            "description": "Start timestamp of this step, 'mm:ss' or 'h:mm:ss'. Omit if unknown.",
            "pattern": "^(\\d{1,2}:)?\\d{1,2}:\\d{2}$"
          }
        }
      }
    },
    "tips": {
      "type": "array",
      "description": "Pro tips, shortcuts, or troubleshooting advice mentioned outside the numbered steps.",
      "items": {
        "type": "string"
      }
    },
    "commonMistakes": {
      "type": "array",
      "description": "Mistakes the creator explicitly warns against. Short phrases. Omit if none.",
      "items": {
        "type": "string"
      }
    }
  }
}

Use it via the API

Pass schemaId: "vidextract.predefined.howto.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.howto.v1"}'

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