How to find news articles with images or videos#

To keep only articles that contain a picture, add has_image=1; to keep only those with a video, add has_video=1. Both are flags that accept exactly 0 or 1. This request returns recent articles that have at least one image:

curl "https://api.apitube.io/v1/news/everything?has_image=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. Without these flags, no media filter is applied and articles with or without media are returned together.

How do has_image and has_video work?#

has_image=1 matches articles whose image count is at least one, and has_video=1 matches articles whose video count is at least one. Set the flag to 0 to do the opposite: has_image=0 returns only articles that have no images, and has_video=0 only articles with no videos. Any value other than 0 or 1 is rejected with a 400 error — has_image returns error code ER0041 and has_video returns ER0042, both with the message that the flag must be 0 or 1.

Every article in the response carries a media array. Each entry in that array has a url and a type, so once results come back you can read the media attached to each article directly.

How to require an exact or minimum number of images#

Use media.images.count to match an exact image count — media.images.count=3 returns only articles that have exactly three images, not three or more. This is the most common surprise with the parameter, so reach for the range variants when you want a threshold:

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

media.images.count.min matches articles with at least that many images, and media.images.count.max caps the count. The same three forms exist for video: media.videos.count, media.videos.count.min and media.videos.count.max. Mixing a minimum and a maximum builds a range — for example, between two and five images:

curl "https://api.apitube.io/v1/news/everything?media.images.count.min=2&media.images.count.max=5&api_key=YOUR_API_KEY"

How to find articles with both images and a video#

Set is_media_rich=1 to require an article to carry at least one image and at least one video at the same time. It is a single shortcut for the common “fully illustrated” case:

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

How to filter for high-resolution images#

Two flags raise the bar on image resolution. has_hq_images=1 keeps articles whose largest image is at least 1200 pixels wide, and has_4k_images=1 requires a width of at least 3840 pixels. Both accept only 0 or 1. This pulls articles with high-quality artwork suitable for large layouts:

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

How to combine media filters with other parameters#

Media parameters stack with each other and with the rest of the filter chain using AND logic — every condition you add narrows the results further. A practical pattern is “articles with a picture, newest first, sorted by how many images they carry”:

curl "https://api.apitube.io/v1/news/everything?has_image=1&sort.by=media.images.count&sort.order=desc&api_key=YOUR_API_KEY"

You can layer any other filter on top. To restrict by the publishing source as well, see How to filter news by source or domain; to narrow by the political lean of those sources, see How to filter news by source political bias. All media parameters are listed in the official News API parameters reference.

Which endpoints support the media filters?#

The media filters belong to the shared filter chain, so they work the same way on the main search and retrieval endpoints — including /v1/news/everything, /v1/news/top-headlines and /v1/news/count. Because /v1/news/count runs the same chain, you can count how many articles carry media without downloading them by sending the same parameters to that endpoint.

Common Questions#

• Does has_image=1 mean exactly one image?
• Why does media.images.count=3 return so few results?
• How do I find articles with no media?
• What does is_media_rich require?

Does has_image=1 mean exactly one image?#

No. has_image=1 matches articles with at least one image, not exactly one. To pin an exact count use media.images.count, and to set a floor use media.images.count.min.

Why does media.images.count=3 return so few results?#

media.images.count is an exact match, so media.images.count=3 only returns articles with precisely three images. If you meant “three or more”, switch to media.images.count.min=3 instead.

How do I find articles with no media?#

Send has_image=0 to return articles with no images, or has_video=0 for articles with no videos. Both flags accept only 0 or 1; any other value returns a 400 error (ER0041 for has_image, ER0042 for has_video).

What does is_media_rich require?#

is_media_rich=1 requires an article to have at least one image and at least one video together. If you only need one or the other, use has_image=1 or has_video=1 instead.