Every Limit the Instagram Reels API Puts on Your Video

What does the Instagram Reels API accept?

A video pushed through the Instagram Reels API has to clear every line of one published specification block before Meta will transcode it, and that block sits in one place: Reel Specifications, in the IG User Media reference. Miss one and the container you created with media_type=REELS comes back with status_code set to ERROR instead of FINISHED.

Here is the whole list, copied from Meta's reference.

How long can a reel be through the API?

Fifteen minutes. Meta's line is "Duration: 15 mins maximum, 3 seconds minimum," which makes the API ceiling far higher than most people expect and the floor higher than most people notice.

The three-second minimum is the one that bites. A clip trimmed to two and a half seconds is a perfectly ordinary asset everywhere else on the internet and an instant rejection here. There is no partial credit and no padding applied on Meta's side.

The fifteen-minute ceiling deserves a caveat Meta does not attach to it. This number governs what the API will accept into a container. It says nothing about what the Instagram app will let a person upload on a phone, and nothing about what the recommendation system will do with a fourteen-minute reel once it exists. Meta attaches exactly that kind of warning to the share_to_feed parameter, noting that neither value "determines whether the reel actually appears in the Reels tab because the reel may not meet eligibilty requirements or may not be selected by our algorithm." The API accepting a file and Instagram distributing it are two different questions.

How big can the file be?

300 MB. Meta writes "File size: 300MB maximum" for reels, and the figure is specific to reels: a story video is capped at "100MB maximum" and an image at "8 MB maximum" on the same page.

If your source file is large or your connection is unreliable, Meta offers a second upload path rather than a bigger cap. Setting upload_type=resumable on the container call returns both an id and a uri, and you then push the bytes to rupload.facebook.com with offset and file_size headers:

curl -X POST "https://rupload.facebook.com/ig-api-upload/v25.0/<IG_CONTAINER_ID>" \
     -H "Authorization: OAuth <ACCESS_TOKEN>" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Meta describes the resumable session as being for "large videos from an area with frequent network interruptions or other transmission failures," and restricts it to apps that have implemented Facebook Login for Business. The 300 MB ceiling still applies.

Which container and codecs work?

MOV or MP4 only, with H264 or HEVC video and AAC audio. Two clauses in Meta's container rule cause more failures than the codec names do.

The first is "moov atom at the front of the file." The moov atom holds the index that tells a player where everything else lives. Encoders write it at the end by default because the sizes are not known until the encode finishes. Moving it to the front is what FFmpeg calls -movflags +faststart, and without it Meta has to read the entire file before it can begin, which is a common source of the download timeout error rather than a format error.

The second is "no edit lists." An edit list is a mapping table that says which parts of a track to play and when. Trimming tools frequently leave one behind instead of re-encoding. The file plays correctly in every desktop player and gets rejected here.

The rest of the video rule, "progressive scan, closed GOP, 4:2:0 chroma subsampling," rules out interlaced footage and open-GOP encodes. A standard H264 export at 4:2:0 satisfies all three without you doing anything.

What frame rate and aspect ratio does Meta require?

Frame rate has to sit between 23 and 60 FPS. Meta writes "Frame rate: 23-60 FPS," which excludes the 15 FPS output that screen recorders and several AI video tools produce by default, and excludes the 120 FPS a phone shoots in slow-motion mode.

Aspect ratio is where Meta's own numbers get strange. The Reels rule is "Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16 to avoid cropping or blank space." A ratio of 0.01:1 is a video one hundred times taller than it is wide. The Story Video Specifications directly below it, describing the same transcoding pipeline, set the same bound at "between 0.1:1 and 10:1." The two figures differ by a factor of ten and both are live on the same page.

Neither bound is a design rule. 9:16 is the design rule, and the 1920 pixel maximum width is what caps resolution in practice. Our note on vertical video dimensions covers where 1080 by 1920 comes from, and the Instagram image size piece covers the separate 4:5 to 1.91:1 range that governs feed photos.

Which error does each violation return?

Meta publishes a subcode table for the Instagram API, and mapping it against the reels specs exposes a gap. Some violations have a dedicated error. Several do not.

Duration is not in that table. Neither is file size, frame rate, or reels aspect ratio. Meta documents an aspect ratio subcode, 2207009, but its own recommended solution describes images: "Advise the app user to try again with an image that falls withing a 4:5 to 1.91:1 range." There is no reels equivalent listed.

The table's own pointer is broken too. Meta's fix for 2207026 reads "Advise the app user to upload an MOV or MP4 (MPEG-4 Part 14). See Video Specifications," and the link lands on a #video-specifications anchor of the IG User Media reference. That page now carries Image Specifications, Reel Specifications, Story Image Specifications and Story Video Specifications. There is no Video Specifications section to land on.

The practical consequence: an over-length or oversized reel most often surfaces as 2207053, the unknown upload error, whose documented remedy is "Generate a new container and use it to try again." That is an unhelpful message for a file that was never going to be accepted, which is the argument for validating duration and size locally before you ever call POST /<IG_ID>/media.

How do you know a reel passed?

Poll the container. Meta's reference is explicit that "Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful," and that you confirm by requesting status_code and waiting for FINISHED. The full set of values and the polling cadence Meta recommends are in the writeup on the Instagram container status_code. If you are wiring the whole flow rather than debugging one file, the walkthrough on scheduling Instagram reels covers the surrounding calls.

Frequently asked questions

What is the maximum reel length through the API?

Fifteen minutes. Meta's Reel Specifications read "Duration: 15 mins maximum, 3 seconds minimum."

What is the maximum file size for a reel?

300 MB. Story videos are capped lower, at 100 MB, in the same reference.

Does the API accept WebM or AVI?

No. Meta lists MOV and MP4 only, and returns subcode 2207026 with the message The video format is not supported for anything else.

Can a reel appear in a carousel?

No. Meta's reels limitations state "Reels cannot appear in carousels."

What aspect ratio should a reel use?

9:16. Meta's own accepted range is far wider, "between 0.01:1 and 10:1," but the same sentence recommends 9:16 "to avoid cropping or blank space."

Does a reel need a cover image?

No. You can pass cover_url or thumb_offset, and Meta defaults thumb_offset to 0, the first frame. If both are supplied, Meta uses cover_url and ignores thumb_offset.

What happens if a reel is trimmed to under three seconds?

Meta rejects it outright. The Reel Specifications set a 3 second minimum, and there's no partial credit or automatic padding added on Meta's side. A clip that works everywhere else on the internet fails here for being too short.

Why does an oversized reel return "unknown upload error" instead of a clear message?

Meta's subcode table has no dedicated entry for duration or file size violations. An over-length or oversized reel most often surfaces as subcode 2207053, whose only documented remedy is to generate a new container and try again. That remedy does nothing for a file that was never going to be accepted, which is why checking duration and size locally before calling the API saves a wasted round trip.

How does the file size cap for a reel compare to a story or an image?

A reel can weigh up to 300 MB. A story video is capped at 100 MB and an image at 8 MB, all on the same IG User Media reference page. The reel allowance runs three times larger than the story limit.

Why would a video that plays fine on a computer get rejected by the API?

Two container details cause most of these failures. An edit list left behind by trimming software, or a moov atom written at the end of the file instead of the front, both play fine in ordinary desktop players yet fail or time out against Meta's reference. Re-encoding with the moov atom moved to the front, FFmpeg's -movflags +faststart, and with no edit list clears both issues.