Instagram Reels user_tags API: usernames only, not on-screen text

To tag people on a Reel through the Instagram API, send user_tags as an array of objects with a public username. The x and y coordinates are only for images and stories, so a Reel needs the username alone. A handle you burn into the pixels with captions is just text: it notifies nobody and tags nobody.

The facts below are from Meta's IG User Media reference, read 2026-10-02, and the changelog. Sume's video captions handles the on-screen version; the tag itself is a publish-time parameter that Sume does not send.

What does user_tags accept on a Reel?

Meta lists user_tags as required for user tagging in images, videos and stories, an array of public usernames. For each object username is required. x and y are floats from 0.0 to 1.0, required for images and optional for stories, and Meta says they apply only to images and stories. The reel container example on the same page lists user_tags alongside collaborators, cover_url, audio_name and location_id.

So the minimum Reel tag is a username and nothing else. The tagged account has to be public.

Why is a burned-in handle not the same thing?

A caption rendered into the video is part of the frames. Instagram never reads it, so there is no tag chip, and no notification. The tag is a field on the container.

The two do different jobs. The tag creates the platform relationship. The on-screen handle helps a viewer who sees the Reel reposted or screen-recorded somewhere without the tag UI. If you want both, keep them consistent: the same spelling, the same account.

How do I burn a handle with Sume?

Standalone video captions accept authored overlay copy as cues with text, start and end in seconds, which skips speech-to-text, so it also works on a silent clip. style and design control the look, and design.placement.anchor_ratio sets the line centre as a fraction of frame height.

The docs list the standalone caption at $0.20 for videos up to 60 seconds; check GET /v1/catalog for the live price. The source video_url must be a fetchable public HTTPS URL.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reel-handle-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/reel.mp4",
    "style": "slam",
    "cues": [{"text": "@ig_user_name", "start": 0.5, "end": 3.0}]
  }'

How do I send the real tag, and what if it fails?

Send user_tags in the same container request as media_type=REELS and video_url. Meta's page shows the encoded form user_tags=%5B%7Busername:ig_user_name%7D%5D for a GET-style request; with a JSON body, send an array.

Tagging can fail after the post succeeds. Since the 2026-09-28 changelog entry, a successful media_publish can include a config_issue field, and USER_TAGGING_FAILURE means the media published without its user tags. Read that field on every publish response instead of assuming the tags landed; see config_issue and caption not attached for the handling pattern.

Also note the caption limits: 2,200 characters, 30 hashtags and 20 @ tags, per Meta's reference.

curl -X POST "https://graph.instagram.com/v26.0/$IG_USER_ID/media" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "media_type": "REELS",
    "video_url": "https://media.sume.com/artifacts/artf_demo/reel-captioned.mp4",
    "user_tags": [{"username": "ig_user_name"}]
  }'

What should I check before bulk-tagging?

Tagging many accounts in one run multiplies the failure modes. Keep the tagged username list next to each video, validate that every account is public before the container call, and cap the list under the caption's own @ tag limit if you also mention people in the caption. A mention in the caption and a tag in user_tags are separate mechanisms with separate failure paths.

If a publish reports USER_TAGGING_FAILURE, do not re-publish the whole Reel: that would create a duplicate post. Log it, and fix the tag in the Instagram app or through the supported edit path.