App Store Header Image and Search Results Video: iOS 27 Sizes, Safe Area and API Upload

iOS 27 added an App Store header image across the top of every product page, and a new search results asset that replaces the old row of three screenshots in search. Both take an image or a looping video. Both can be localized. And both also work on custom product pages, so each ad keyword group can land on its own header.

We've now shipped headers and search videos for several apps, in 39 languages each, and for a stack of custom product pages, almost entirely by working through AI coding agents. This guide has the numbers you need, the pipeline we use, and the problems that cost us the most time.

The Specs at a Glance

All figures come from Apple's creative assets specifications.

Videos run at 30 or 60 fps, last between 5 and 30 seconds, and loop. On the product page they start muted and people can unmute them. In search results they're muted and can't be unmuted. No image may have an alpha channel.

The assets appear only on iOS 27 and iPadOS 27 and later. Anyone on an older version still sees your screenshots, which matters more than it sounds (see Do screenshots still matter).

Safe Areas: Smaller Than You Think

The header is cropped differently on every device and orientation. Only the middle survives everywhere. Apple's asset best practices say to keep the focal artwork in the centre, and the official templates mark the safe rectangle:

Product page header 21:9

3,840 × 1,646 px

That's 17.2% of the header canvas. Everything that has to be read, a face, a product or a phrase, goes inside it. The rest is atmosphere. We also kept the lower third of the header calm, with no text or busy motion, because it reads poorly once the page UI sits around it.

Search results 3:2

3,840 × 2,560 px

Universal (both placements) 16:9

5,244 × 2,950 px

The header rectangle is the one in Apple's header template, and it's the one we design against. The search results and universal sizes are measurements of Apple's templates published by StoreHeader; check them against the template before you rely on the edges.

The universal asset sounds convenient, but its safe area is the smallest of the three in relative terms, and it can't be a video. If you want motion, make two dedicated files.

What the App Store Won't Accept in the Artwork

From Apple's best practices, the creative must not include:

• Prices, discounts, website URLs or copyright symbols.
• Claims you can't verify, such as awards you haven't won.
• Logos of other platforms or stores.
• Apple recognitions like Editor's Choice or App of the Day.
• Anything above a 4+ age rating, even if your app is rated higher.

Keep text to a short phrase that adds to the picture instead of describing it, and translate it for every language you support. Review applies App Review Guideline 2.3 to these assets too.

How We Build Them with Claude Code or Codex

Nothing here needs a design tool. An AI coding agent can build the whole pipeline in a repo, and you review the frames. The pipeline has five steps:

1. A deterministic motion page. One HTML file draws the scene for any time t through a renderAt(t) function, at the exact canvas size. No real-time animation, no screen recording. The same t always produces the same frame.
2. A frame grabber. A headless browser steps t from 0 to the loop length at 30 fps and saves each frame. Frames that don't change between languages get cached.
3. An encoder. ffmpeg turns the frames into an MP4 with fixed settings (next section).
4. A verifier. ffprobe checks every file: size, frame rate, duration, codec level, colour tags, no audio. A few frames get pulled out for a quick visual check.
5. An uploader. A script talks to the App Store Connect API (covered below).

Prompts that worked for us are specific about numbers and about proof. For example:

Build header/motion.html that renders a 3840×1646 frame for any time t via renderAt(t). Keep every text element and focal object inside x 1097–2743, y 493–1154, and add a ?guide=1 overlay that draws that box. Loop length 10 s, and the last frame must match the first. Then write grab.mjs to export 30 fps PNG frames with Playwright, and verify.sh that fails if any file isn't 3840×1646, 30 fps, 10.0 s ±0.05 s, H.264 High, with no audio stream.

Ask for the guide overlay every time. It's the fastest way to see when something drifts out of the safe area.

Video Settings That Don't Stutter

Apple doesn't play your file. It re-encodes it and streams it as HLS. In our measurements Apple's copies were at most 1918 pixels wide and split into segments of about 3.3 to 4 seconds. Our first search results video froze for about four seconds right at the first segment boundary on every loop. The header encoded with the same tools played fine.

We found five risky things in our files:

• The search video was 3840 × 2560, which pushes H.264 past level 5.2.
• Frames exported as JPEG produced full-range yuvj420p video instead of standard TV range.
• B-frames plus an MP4 edit list shifted the start time.
• The longer search loop was made by joining copies with -c copy, which leaves timestamp seams.
• Bitrate peaks reached 12 to 14 Mbps.

What we use now for every creative video:

• Header at 3840 × 1646. Search at 2880 × 1920, which is inside Apple's range and keeps H.264 at level 5.1 or below.
• H.264 High, yuv420p, TV range, tagged bt709.
• No B-frames, a fixed 1-second GOP, a capped bitrate, faststart, no audio track.
• The full duration encoded in one pass. To loop twice, feed the same frame sequence to the encoder twice. Never join finished files.

ffmpeg -framerate 30 -i frames/%05d.png \
  -c:v libx264 -profile:v high -pix_fmt yuv420p \
  -color_range tv -colorspace bt709 -color_primaries bt709 -color_trc bt709 \
  -bf 0 -g 30 -keyint_min 30 -sc_threshold 0 \
  -maxrate 12M -bufsize 24M -movflags +faststart -an \
  search_2880x1920.mp4

On length, Apple's page says 5 to 30 seconds. The API's reference data hinted at higher minimums for some placements, so we export 18 to 20 seconds (a short loop played twice), which satisfies either reading.

Before you upload a batch, upload a single file to a draft custom product page and watch Apple's processed copy play all the way through. A local file that plays well proves very little.

Uploading Through the App Store Connect API

App Store Connect API 4.5.1 added the App Asset Library. Every asset is uploaded once, then attached to surfaces with placements. For a header video the flow is:

1. POST /v1/appAssetLibraryVideos with category CREATIVE_ASSETS, the file name, size and a referenceName. The response contains upload operations.
2. PUT each part of the file to the URLs in those operations.
3. PATCH the video with uploaded: true, then poll its state until processing finishes.
4. POST /v1/appAssetLibraryPlacements once per localization, with placementType set to PRODUCT_PAGE_HEADER_ASSET or APP_STORE_SEARCH_RESULTS_ASSET and a relationship to an appStoreVersionLocalization or an appCustomProductPageLocalization.

Because placements point at the library asset, one video can serve many languages. Apple's placement guide lists the three errors you'll meet most: a placement type and asset category that don't match, a parent that's already approved, and a group that's over its limit.

You can also submit creative assets on their own through the Asset Library, without a new app version. Apple reviews standalone assets against your latest app version, per App Store Connect Help.

Problems We Hit, and the Fixes

Uploads stalled or reset halfway. Large video uploads to Apple's storage sometimes stopped moving or dropped the connection. Fixes: a fresh connection for every API request, a connect timeout, aborting any transfer that stops progressing, retries on 429 and failed GETs, and no more than four uploads in parallel.

Re-runs uploaded the same file again. Use a unique referenceName per file and look it up before uploading. A video that already finished processing can be reused. A reservation stuck waiting for its upload gets deleted and created again.

Placements on an approved custom product page failed. An approved page version is locked. Add a new version to the custom product page first, or create a new page from the live version, then place the assets on that version's localizations.

Animated overlays slipped out of the safe area. A moving magnifier or label can start inside the box and end outside it. Anchor every moving element to the reachable part of the safe area, and check frames with the guide overlay turned on.

The first frames came out blank. Images hadn't finished decoding when frame zero was captured. Decode every image before you render the first frame.

Localization is by language, not country. Like screenshots, the header belongs to an App Store localization, not to a storefront country. Plan seasonal scenes (a holiday header, for instance) per language, and remember that every swap goes through review.

Volume adds up fast. 39 languages × 2 placements is 78 placements for a single version, before any custom product pages. Automate it from the start, and read back every placement after writing it.

Do Screenshots Still Matter?

Yes, for now. Before iOS 27, search shows your first three screenshots, and everyone who opens your product page still sees the full screenshot gallery. In one set of App Store Connect analytics we checked in early October 2026, iOS 27 accounted for about 15% of search impressions and iOS 26 for about 66%. The header wins the new users first. Screenshots still do most of the work this quarter.

Frequently Asked Questions

What size is the App Store header image?

3840 × 1646 pixels at 21:9, as JPEG or PNG, or as a video at the same size. A 5244 × 2950 PNG at 16:9 can also serve both the header and search results.

What is the safe area of the App Store header?

A centred 1646 × 661 pixel rectangle, from x 1097 to 2743 and y 493 to 1154. That's 17.2% of the canvas. Keep text, faces and the product inside it.

What size is the App Store search results asset?

3:2, from 1920 × 1280 up to 3840 × 2560 pixels. For video we recommend 2880 × 1920, because 3840 × 2560 pushes H.264 beyond level 5.2.

Can custom product pages have their own header?

Yes. Custom product page localizations accept header and search results placements, so each page can show the header that matches its keywords or ad group.

Why does my App Store header video stutter?

Apple re-encodes it into HLS segments of a few seconds. Files with B-frames, edit lists, full-range colour or joined segments can freeze at a segment boundary. Re-encode with no B-frames, a fixed 1-second GOP, yuv420p in TV range and a single pass over the full duration.

Can I localize the header per language?

Yes. Each placement belongs to one App Store localization, so every language can get its own header and search video, with translated text or a scene that fits that market. One uploaded video can also be placed on many localizations.

Which iOS versions show these assets?

iOS 27 and iPadOS 27 and later. Earlier versions show screenshots, app previews and in-app events instead.

Can Claude Code or Codex make and upload these assets?

Yes. Ask the agent to build a deterministic HTML scene, a frame grabber, an ffmpeg encoder with fixed settings, an ffprobe verifier and an API uploader. Review the frames yourself before anything is uploaded, and approve each upload explicitly.

Sources

• Apple, Creative assets specifications
• Apple, App Store asset best practices
• Apple, Manage your App Store assets
• Apple, App Store Connect API 4.5.1 release notes
• Apple, Understanding the app asset library
• Apple, Placing assets on your App Store surfaces
• Apple, App Review Guidelines
• StoreHeader, App Store creative asset sizes (search results and universal safe areas)

Related research from TrendApps data

• App Store Ranking Factors: which listing fields the App Store indexes and how conversion feeds rank.
• Best ASO Tools 2026: including Custom Product Pages as a free A/B testing path.

---

Want to see which apps in your category already use video headers and how their rank moves? Trend Apps tracks ranking, download and revenue movement across the App Store and Google Play.