History Explainer

A history explainer or documentary extracted from a video — covering a historical period, event, civilization, or figure. Capture only what the narrator states; omit anything not mentioned and do not infer.

Fields

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "vidextract.predefined.history.v1",
  "title": "History Explainer",
  "description": "A history explainer or documentary extracted from a video — covering a historical period, event, civilization, or figure. Capture only what the narrator states; omit anything not mentioned and do not infer.",
  "type": "object",
  "required": [
    "title",
    "summary",
    "keyEvents"
  ],
  "additionalProperties": false,
  "properties": {
    "title": {
      "type": "string",
      "description": "Title of the topic, e.g. 'The Fall of the Roman Empire'."
    },
    "summary": {
      "type": "string",
      "description": "Two to four sentences summarizing the historical narrative covered."
    },
    "topic": {
      "type": "string",
      "description": "The central subject, e.g. 'Roman Empire', 'French Revolution', 'World War II'."
    },
    "era": {
      "type": "string",
      "description": "Broad historical era or period as described, e.g. 'Classical Antiquity', '18th century'. Omit if not stated."
    },
    "timePeriod": {
      "type": "string",
      "description": "Date range covered, as stated, e.g. '753 BC – 476 AD'. Omit if not stated."
    },
    "regions": {
      "type": "array",
      "description": "Geographic regions, empires, or places central to the narrative, e.g. 'Italy', 'Mediterranean'.",
      "items": {
        "type": "string"
      }
    },
    "keyFigures": {
      "type": "array",
      "description": "Important people discussed.",
      "items": {
        "type": "object",
        "required": [
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "Person's name, e.g. 'Julius Caesar'."
          },
          "role": {
            "type": "string",
            "description": "Their role or significance, e.g. 'Roman general and dictator'. Omit if not stated."
          }
        }
      }
    },
    "keyEvents": {
      "type": "array",
      "description": "Significant events in chronological order as presented.",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "event"
        ],
        "additionalProperties": false,
        "properties": {
          "event": {
            "type": "string",
            "description": "What happened, e.g. 'The sack of Rome by the Visigoths'."
          },
          "date": {
            "type": "string",
            "description": "When it happened, as stated, e.g. '410 AD'. Omit if not stated."
          },
          "significance": {
            "type": "string",
            "description": "Why it mattered, per the narrator. Omit if not stated."
          },
          "videoTimestamp": {
            "type": "string",
            "description": "Start timestamp in source video, 'mm:ss' or 'h:mm:ss'. Omit if unknown.",
            "pattern": "^(\\d{1,2}:)?\\d{1,2}:\\d{2}$"
          }
        }
      }
    },
    "causes": {
      "type": "array",
      "description": "Stated causes, drivers, or contributing factors behind the main developments. Short phrases.",
      "items": {
        "type": "string"
      }
    },
    "consequences": {
      "type": "array",
      "description": "Stated outcomes, effects, or lasting legacy. Short phrases.",
      "items": {
        "type": "string"
      }
    },
    "themes": {
      "type": "array",
      "description": "Recurring themes or throughlines the narrator emphasizes, e.g. 'political corruption', 'military overreach'.",
      "items": {
        "type": "string"
      }
    },
    "keyTakeaways": {
      "type": "array",
      "description": "Main conclusions or lessons the narrator draws. Short sentences.",
      "items": {
        "type": "string"
      }
    }
  }
}

Use it via the API

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

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