find_packaging
Find packaging: the titles and thumbnails that earned the click on a topic, from
long-form YouTube videos that beat their own channel.
What it does: runs the same outlier search as find_long_hooks (long-form YouTube,
2023 or later, views at least min_outlier times the channel's usual), then looks at
each video's thumbnail beside its title and says what the pair is doing.
What comes back: the run's `finds`, ranked. Each is a real package, as YouTube shows
it: title (verbatim) and thumbnail_url (the size YouTube really served, the picture
the analysis looked at; thumbnail_checked says so), channel, watch_url, views,
channel_median_views, outlier, outlier_score (0 to 100 on one fixed scale, so finds
from different runs rank together), outlier_tier, channel_size and posted_at, plus the analysis: title_device (curiosity_gap, contrarian_claim,
specific_number, how_to, listicle, challenge, story, question, warning, comparison,
authority, timeliness, identity_callout, other), title_template (the title as a
fill-in structure), thumbnail_text (the words printed on the thumbnail, read by a vision
model; null when none), thumbnail_text_role (repeats_title, adds_to_title,
contrasts_title, no_text; counted from title_overlap, the share of the thumbnail's words
that are also in the title, where that can be), thumbnail_subject, thumbnail_faces,
thumbnail_emotion,
thumbnail_colors, thumbnail_composition, thumbnail_devices, angle, gap (what the picture shows that the title does not say, and the
question that leaves), promise, steal_it and audience, visible_action (the single thing
happening in the picture), title_carries and picture_adds (what only the title says,
what only the picture adds), text_box, and thumb_metrics (measured in code from the
pixels: palette, brightness, contrast, saturation, busyness, the biggest words' height
at 210 px wide and whether the length corner is clear), plus cut_on_phone (the title is
longer than 60 characters, where a phone roughly cuts it; approximate) and on_subject
(yes or partly: whether the look judged the package to be about your topic; a package
judged not to be is dropped and the next one takes its slot; null on a link run). analysed
is false when a package could not be looked at (its look is asked twice, and the next
candidate takes the slot if it fails twice); it is still a real package.
The run's report then holds title_patterns and thumbnail_patterns (what at least two
of the packages share, each naming their video_ids) and ideas: up to `ideas` (6 by
default, 0 for none) packages WRITTEN for your topic from those patterns, each a title
a thumbnail concept and thumbnail_text (the words to print on it), naming the real
packages it is based_on. report.ideas_label is always "Written by Hook Detector from
the patterns in these real packages": show it with them, never present an idea as a
real video's title; an idea over 70 characters, with more than 5 words for its
thumbnail or repeating a real title is dropped. report.numbers counts the packages:
title_chars and title_words
(medians), titles_with_number, titles_with_question, titles_cut_on_phone (with
phone_title_chars, the approximate length a phone cuts a title at), thumbnails_with_text
and thumbnail_words (over the analysed ones), and the title_devices, thumbnail_devices and
emotions that repeat (name, count); age_cohorts repeats the counts for packages posted in
the last split_days days (recent) and for older ones, with the undated apart.
report.landscape is the subject at a glance, as on find_long_hooks.
Arguments: topic 3 to 500 characters, or a channel's or a long-form video's YouTube
address exactly as on find_long_hooks (a channel's own outliers, or that one video; no
ideas are written for a link, use remix_find); count 1 to 30 (default 12); language,
country, min_outlier, posted_within_days, channel_size and reuse as on
find_long_hooks; idempotency_key and wait_seconds as on find_hooks; content_type
"short" finds the packages of YouTube Shorts instead of long-form videos ("long", the
default), each Short measured against its own channel's Shorts. Every find carries
multiple (views over the channel's median, the number 1of10 and vidIQ show),
multiple_band (10x, 5x, 2x, under 2x) and content_type.
Cost: reserves up to 70 credits for 24 packages or fewer and 3 more for each package
above that (88 at 30; down to 25) and charges only the provider calls it
made: the searches, one call per channel measured, and one for each video whose date
had to be read exactly. Looking at a thumbnail costs no credit. After a find_long_hooks run on the same topic it is close
to free. A failed run costs nothing, and so does a run that finds nothing, inside the
allowance.
Timing and next step: how long a run takes has not been measured yet, so never assume
a time. Call get_run with wait_seconds=50 until status is done or failed;
progress.items holds the packages looked at so far as cards and progress.scan the videos
it is looking at while it runs. Same as POST /v1/packaging. Needs the research
permission.
Schema valid · SHA-256 c4aa3703d103…
View input schema
{
"type": "object",
"properties": {
"topic": {
"description": "the subject to research, 3 to 500 characters, in any language. Or a YouTube address instead of a subject: a channel's (https://www.youtube.com/@name, or just @name) returns that channel's own outliers, its recent long-form uploads that beat its usual; a long-form video's (https://www.youtube.com/watch?v=...) returns that one video, whatever its multiple. A Short's address is refused (422)",
"examples": [
"home espresso",
"https://www.youtube.com/@name"
],
"maxLength": 500,
"minLength": 3,
"title": "Topic",
"type": "string"
},
"count": {
"default": 12,
"description": "how many packages to deliver, 1 to 30",
"maximum": 30,
"minimum": 1,
"title": "Count",
"type": "integer"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "optional, up to 60 characters: the language the videos should be spoken in, in words or as a tag (\"Spanish\", \"pt-BR\"). Left out, it is read from the topic's own language",
"examples": [
"Spanish"
],
"maxLength": 60,
"title": "Language"
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "optional, an assigned ISO 3166-1 alpha-2 code (US, GB, MA): searches YouTube as seen from this country. It steers the search; it does not filter the channels",
"examples": [
"US"
],
"pattern": "^[A-Za-z]{2}$",
"title": "Country"
},
"min_outlier": {
"default": null,
"description": "optional, 1.5 to 100 (default 2): how many times its own channel's usual views a video must have to count as an outlier. Only outliers are ever delivered",
"examples": [
3
],
"maximum": 100,
"minimum": 1.5,
"title": "Min Outlier",
"type": [
"number",
"null"
]
},
"posted_within_days": {
"default": null,
"description": "optional, how recent the videos must be, as days: 30, 90, 365, 730. Null or left out means everything since 2023-01-01; nothing older is ever delivered",
"enum": [
30,
90,
365,
730,
null
],
"examples": [
365
],
"title": "Posted Within Days",
"type": [
"integer",
"null"
]
},
"channel_size": {
"default": null,
"description": "optional: only videos from channels of this size, by what the channel's uploads usually get (its median views, the figure the outlier is measured against): small (under 20,000), medium (up to 200,000) or large. Null or left out: any size",
"enum": [
"small",
"medium",
"large",
null
],
"examples": [
"small"
],
"title": "Channel Size",
"type": [
"string",
"null"
]
},
"ideas": {
"default": null,
"description": "optional, 0 to 10 (default 6): how many written packages (a title and a thumbnail concept) to add for the subject; 0 for none",
"examples": [
6
],
"maximum": 10,
"minimum": 0,
"title": "Ideas",
"type": [
"integer",
"null"
]
},
"reuse": {
"default": true,
"description": "start from the videos your last long or packaging run on this topic already bought (within a week), so the second tab on a topic costs little",
"title": "Reuse",
"type": "boolean"
},
"wait_seconds": {
"default": 0,
"description": "0 to 50: seconds to wait for the run to finish; 0 returns at once",
"maximum": 50,
"minimum": 0,
"title": "Wait Seconds",
"type": "integer"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "1 to 255 visible ASCII characters; the same key within 24 hours returns the first run instead of paying for a second",
"title": "Idempotency Key"
},
"content_type": {
"default": null,
"description": "optional: \"long\" (long-form videos, the default) or \"short\" (YouTube Shorts): the kind of video whose packages to find. A Short is measured against its own channel's Shorts",
"enum": [
"long",
"short",
null
],
"examples": [
"short"
],
"title": "Content Type",
"type": [
"string",
"null"
]
},
"filters": {
"default": null,
"description": "optional bounds, every one optional: min_multiple and max_multiple (views over the channel's median, 1 to 1000), min_views, max_views, min_channel_median, max_channel_median, min_duration_s, max_duration_s; on the Library (and a library preset) also min_comments, max_comments, posted_within_days (7, 30, 90, 365, 730) and language. No delivered find falls outside one; a min_multiple above the bar raises it",
"examples": [
{
"max_views": 2000000,
"min_multiple": 5
}
],
"title": "Filters",
"type": [
"object",
"null"
]
},
"preset_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "optional: start from a saved preset of this tab (save_preset); filters sent with it win over the preset's",
"title": "Preset Id"
},
"api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Api Key"
}
},
"required": [
"topic"
],
"title": "find_packagingArguments"
}