How to filter by media quality and social-ready images#

To return only articles whose images meet a quality bar, add a media flag such as has_hq_images=1 (images at least 1200px wide) to your News API request. For example, this keeps articles that carry a high-quality image:

curl "https://api.apitube.io/v1/news/everything?has_hq_images=1&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. Every media flag is a 0/1 toggle: pass 1 to require the condition. Each of these filters runs on the shared filter chain, so the same parameters work on /v1/news/everything, /v1/news/top-headlines and /v1/news/count.

How to filter by image resolution#

Three flags gate articles by the width of their largest image, each with a fixed pixel threshold:

• has_hq_images=1 — at least one image is 1200px wide or more.
• has_fullhd_images=1 — at least one image reaches Full HD width (1920px+).
• has_4k_images=1 — at least one image reaches 4K width (3840px+).

This request returns only articles that ship a 4K-width image:

curl "https://api.apitube.io/v1/news/everything?has_4k_images=1&api_key=YOUR_API_KEY"

There is also has_mobile_optimized_images=1, which matches articles whose largest image sits in the 320–800px range — handy when you want lightweight images for a mobile feed rather than the biggest file available.

What does is_media_rich actually require?#

is_media_rich=1 is stricter than it sounds: it matches articles that contain both at least one image and at least one video. It is not a “lots of images” flag — an article with ten photos and no video will not match is_media_rich=1. Use it when you specifically need mixed image-and-video coverage:

curl "https://api.apitube.io/v1/news/everything?is_media_rich=1&api_key=YOUR_API_KEY"

If you only care about images or only about videos, use has_image=1 or has_video=1 instead, or set explicit counts with media.images.count.min and media.videos.count.min.

How to find Instagram- and Twitter-ready images#

Two flags pre-check images against social-platform dimensions so you don’t have to inspect pixels yourself:

• is_instagram_ready=1 — at least 1080px wide with a roughly square or 4
  portrait aspect ratio.
• is_twitter_card_ready=1 — at least 800px wide and landscape (wider than it is tall).

There is also has_social_share_image=1, which matches Open Graph–compatible images that are at least 1200×630px — the size used for link previews when an article is shared. To pull recent articles that already have a share-ready preview image:

curl "https://api.apitube.io/v1/news/everything?has_social_share_image=1&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

How to set exact image dimensions and counts#

When the preset flags aren’t precise enough, control the numbers directly. The media.images.count parameter (plus .min and .max variants) bounds how many images an article must have, and media.images.width.min/max and media.images.height.min/max bound their pixel size:

curl "https://api.apitube.io/v1/news/everything?media.images.count.min=2&media.images.width.min=1200&media.images.height.min=630&api_key=YOUR_API_KEY"

This returns articles with two or more images, each pipeline-measured at 1200px wide and 630px tall or larger. Related flags refine shape and quantity: has_multiple_images=1 requires two or more images, while is_landscape_media=1 and is_portrait_media=1 filter by orientation, and has_thumbnail=1 requires a small image (300px wide or less) to exist.

What values do the media filters accept?#

Every boolean media flag accepts only 0 or 1. Passing anything else — for example has_4k_images=2 — returns an HTTP 400 with a specific error code (ER0254 for has_4k_images, ER0233 for is_media_rich, and so on). The numeric parameters like media.images.count must be non-negative integers, otherwise the request also fails with a 400. These filters stack with any other filter, so you can combine media quality with bias, language or category in one call — see How to filter news by source political bias for a stacking example, and the official News API parameters reference for the full list.

Common Questions#

• Does is_media_rich mean “has many images”?
• Which pixel widths do the resolution flags use?
• Can I combine media filters with other filters?
• What happens if I pass an invalid value?

Does is_media_rich mean “has many images”?#

No. is_media_rich=1 requires an article to have at least one image and at least one video together. An article with many images but no video does not match. For image-only or video-only needs, use has_image=1, has_video=1, or explicit media.images.count.min / media.videos.count.min values.

Which pixel widths do the resolution flags use?#

has_hq_images checks for an image 1200px wide or wider, has_fullhd_images for 1920px+, and has_4k_images for 3840px+. is_instagram_ready needs 1080px+ with a square or 4

ratio, is_twitter_card_ready needs 800px+ landscape, and has_social_share_image needs at least 1200×630px.

Can I combine media filters with other filters?#

Yes. The media filters run in the same shared filter chain as language, source, category and sentiment filters, so you can stack them freely in a single request. For example, you can require a 4K image and read time together, or filter for high-quality images in one language sorted newest-first.

What happens if I pass an invalid value?#

A boolean flag with a value other than 0 or 1 returns an HTTP 400 and a filter-specific error code (such as ER0254 for has_4k_images). A numeric parameter such as media.images.count that is not a valid non-negative integer also returns a 400, so the request fails fast instead of silently ignoring the value.