{
  "openapi": "3.0.1",
  "info": {
    "title": "Youtube Highlights Hooks Analyzer",
    "description": "Advanced YouTube analytics that extracts chapters, intro pacing, and hook suggestions for editors and creators. Analyze Shorts and long videos to find viral moments, engagement patterns, and optimal clip timestamps with an API-first design for blazing-fast performance.",
    "version": "1.9",
    "x-build-id": "iCmfQXKMXWD0yc0mk"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/coregent~youtube-highlights-hooks-analyzer/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-coregent-youtube-highlights-hooks-analyzer",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/coregent~youtube-highlights-hooks-analyzer/runs": {
      "post": {
        "operationId": "runs-sync-coregent-youtube-highlights-hooks-analyzer",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/coregent~youtube-highlights-hooks-analyzer/run-sync": {
      "post": {
        "operationId": "run-sync-coregent-youtube-highlights-hooks-analyzer",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "videoRefs": {
            "title": "Video URLs or IDs",
            "type": "array",
            "description": "Specific videos to analyze. Accepts video URLs (watch, youtu.be, /shorts/, /embed/) or raw 11-character video IDs. Only the videos you list here are analyzed — one record per video. To analyze whole channels, playlists, or a seed video's channel, use the \"Discovery Sources\" input below instead.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "channelPlaylistRefs": {
            "title": "Discovery Sources",
            "type": "array",
            "description": "Sources to discover videos from. Accepts four kinds of entries: (1) channel URLs (youtube.com/@handle, /channel/UC..., /c/..., /user/...), (2) playlist URLs (...?list=...), (3) seed video URLs or IDs, and (4) plain search keywords (e.g. \"ai automation tutorial\"). Channels and playlists expand into their videos; a seed video is resolved to its owning channel and that channel's videos are analyzed (not just the seed video); a search keyword returns the top matching videos from YouTube search. A video URL here analyzes its whole channel — to analyze only that one video, use the \"Video URLs or IDs\" input above instead. Each source is capped by \"Max videos per source\". Unlike the video input, discovery sources DO respect the Published after/before, view-count and duration filters below, and search keywords honour the \"Sort Search Results By\" setting.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "maxVideosPerSource": {
            "title": "Max videos per source",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Cap how many videos to take from each discovery source (channel, playlist, seed-video-derived channel, or search keyword). Does not affect videos listed in the \"Video URLs or IDs\" input. The overall run is still bounded by \"Max Videos to Analyze\" below.",
            "default": 50
          },
          "maxVideos": {
            "title": "Max Videos to Analyze",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Maximum number of videos to analyze across all sources. Capped at 500: a search-driven run consumes 100 YouTube API quota units per 50 videos, and the daily quota is 10,000 units, so 500 videos is already a fifth of a day's capacity.",
            "default": 50
          },
          "since": {
            "title": "Published After",
            "type": "string",
            "description": "Only analyze videos published after this date"
          },
          "until": {
            "title": "Published Before",
            "type": "string",
            "description": "Only analyze videos published before this date"
          },
          "minViews": {
            "title": "Minimum Views",
            "minimum": 0,
            "type": "integer",
            "description": "Only analyze videos with at least this many views (0 = no minimum)",
            "default": 0
          },
          "maxViews": {
            "title": "Maximum Views (optional)",
            "minimum": 0,
            "type": "integer",
            "description": "Only analyze videos with at most this many views (leave empty for no maximum)"
          },
          "durationFilter": {
            "title": "Video Duration",
            "enum": [
              "any",
              "shorts",
              "under_4m",
              "4_to_20m",
              "over_20m"
            ],
            "type": "string",
            "description": "Filter videos by length. 'Shorts' keeps videos of 3 minutes or less, matching YouTube's current Shorts limit (it was 60 seconds before 2024). Note that YouTube's search API can only narrow to 'under 4 minutes', so the remainder is filtered afterwards — the actor requests extra results to compensate, at no additional quota cost.",
            "default": "any"
          },
          "maxHooksPerVideo": {
            "title": "Max Hooks Per Video",
            "minimum": 1,
            "maximum": 25,
            "type": "integer",
            "description": "Maximum number of hook suggestions to generate per video (recommended: 5-15). Shorts are automatically capped at 5 regardless of this setting.",
            "default": 10
          },
          "hookLengthSec": {
            "title": "Hook Clip Length (seconds)",
            "minimum": 3,
            "maximum": 15,
            "type": "integer",
            "description": "Suggested length for hook clips in seconds (3-15s recommended for Shorts/TikTok)",
            "default": 7
          },
          "transcriptLanguage": {
            "title": "Transcript Language",
            "enum": [
              "",
              "en",
              "es",
              "de",
              "fr",
              "pt",
              "ja",
              "hi",
              "zh",
              "ko",
              "ru",
              "ar",
              "bn",
              "ta",
              "te",
              "mr",
              "gu",
              "kn",
              "ml",
              "ur",
              "pa",
              "th",
              "vi",
              "id",
              "tr",
              "it",
              "nl",
              "pl",
              "uk",
              "ro",
              "cs",
              "sv",
              "da",
              "fi",
              "no"
            ],
            "type": "string",
            "description": "Preferred caption language. On 'Auto' the actor prefers English, then any manually-created track, then whatever exists. This matters on multi-language videos — some carry dozens of tracks, and picking the wrong one degrades hook titles, which are generated from transcript text. If the chosen language has no track, the actor falls back rather than returning nothing.",
            "default": ""
          },
          "fetchReplayHeatmap": {
            "title": "Most-Replayed Enrichment (extra charge)",
            "type": "boolean",
            "description": "Adds YouTube's public Most-Replayed curve: 100 intensity buckets, peak timestamps, and replay-weighted highlight ranking. This is a PAID ENRICHMENT with its own per-result charge, billed only when a curve is actually returned — videos with no published graph cost you nothing. Off by default. Note that not every video has one; YouTube publishes the graph only after a video accumulates enough watch history. Adds roughly 1-2 seconds per video.",
            "default": false
          },
          "heatmapRequestTimeoutSecs": {
            "title": "Heat Map Request Timeout (seconds)",
            "minimum": 5,
            "maximum": 120,
            "type": "integer",
            "description": "Per-request timeout for the heat map page fetch.",
            "default": 20
          },
          "heatmapMaxRetries": {
            "title": "Heat Map Max Retries",
            "minimum": 0,
            "maximum": 5,
            "type": "integer",
            "description": "Retries for a failed heat map page fetch before giving up on that video's replay data. Analysis continues either way.",
            "default": 2
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}