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.Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"topic": "<topic>"
},
"name": "find_packaging"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | how many packages to deliver, 1 to 30 | |
| ideas | No | optional, 0 to 10 (default 6): how many written packages (a title and a thumbnail concept) to add for the subject; 0 for none | |
| reuse | No | 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 | |
| topic | Yes | 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) | |
| api_key | No | ||
| country | No | 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 | |
| filters | No | 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 | |
| language | No | 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 | |
| preset_id | No | optional: start from a saved preset of this tab (save_preset); filters sent with it win over the preset's | |
| min_outlier | No | 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 | |
| channel_size | No | 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 | |
| content_type | No | 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 | |
| wait_seconds | No | 0 to 50: seconds to wait for the run to finish; 0 returns at once | |
| idempotency_key | No | 1 to 255 visible ASCII characters; the same key within 24 hours returns the first run instead of paying for a second | |
| posted_within_days | No | 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 |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |