Turn an authorized Instagram Reel link into a media-library record

#javascript #tutorial #api

A creator sends your content tool a link to one of their own public Instagram Reels. Your application needs a caption, thumbnail, duration, and a video URL for an immediate preview. A social-page URL is not a direct media-file URL, so the first step is to resolve it into structured data.

This tutorial uses Instagram Reel Video & Metadata API, an independently operated product I provide through RapidAPI and API.market. It supports public Reel videos you own or have permission to process. It requires no Instagram login or cookies. It does not support private content, Stories, Posts, account access, or permanent media hosting.

Start offline

The public sample repository includes JavaScript and Python clients with no third-party dependencies. Use Node.js 22+ or Python 3.11+. Clone the repository and run:

git clone https://github.com/flyrory/instagram-reel-api-examples.git
cd instagram-reel-api-examples

Then preview either client:

node resolve.mjs --demo
# Python alternative:
python3 resolve.py --demo

You will get synthetic JSON:

{
  "success": true,
  "source_url": "https://www.instagram.com/reel/DEMO/",
  "shortcode": "DEMO",
  "media_type": "video",
  "video_url": "https://media.example.invalid/reel.mp4",
  "thumbnail_url": "https://media.example.invalid/thumbnail.jpg",
  "caption": "Synthetic preview of your authorized Reel.",
  "duration_seconds": 12.5
}

These media URLs deliberately do not resolve. No key or network request is needed for this preview.

Connect your marketplace subscription

Subscribe to BASIC on RapidAPI, then set your consumer RAPIDAPI_KEY privately in your local environment. Keep keys on your backend and out of source control, screenshots, and browser code.

export MARKETPLACE=rapidapi
export SAMPLE_REEL_URL='https://www.instagram.com/reel/YOUR_SHORTCODE/'
# Privately set RAPIDAPI_KEY before running the client.
node resolve.mjs --authorized
# Or:
python3 resolve.py --authorized

Replace YOUR_SHORTCODE with an actual public Reel you own or may process. The --authorized flag confirms your permission; it does not create it. To use API.market, set MARKETPLACE=api_market and privately set API_MARKET_KEY.

The request is POST /v1/media/resolve through the selected marketplace, with a JSON body containing one url. The samples use fixed marketplace gateways, refuse redirects, and apply a 20-second timeout. They do not need supplier-origin credentials.

Save a record that remains useful

Treat the source Reel URL as the reference you can resolve again. Your library record might contain:

{
  "source_url": "https://www.instagram.com/reel/DEMO/",
  "shortcode": "DEMO",
  "caption": "Synthetic preview of your authorized Reel.",
  "duration_seconds": 12.5,
  "resolved_at": "2026-10-12T00:00:00Z"
}

resolved_at is added by your application, not returned by the API. Caption, thumbnail, and duration depend on what is available upstream. A returned media URL is temporary: use it immediately for your authorized workflow, and resolve the source again when needed. It is unsuitable as a permanent video or thumbnail storage key. The API does not archive media for you.

Handle unavailable content and limits

Try node resolve.mjs --demo --status 404 or the equivalent Python command to exercise an unavailable-content path offline. The client exits with a nonzero status and prints recovery guidance instead of reporting success.

HTTP status	Application behavior
400	Ask for a supported public Reel URL and check the JSON.
401 / 403	Check the marketplace subscription and consumer key.
404	Mark this source as unavailable; do not repeatedly retry it.
429	Check allowance, slow requests, and respect `Retry-After` when present.
502 / 503 / 504	Offer a later retry with bounded backoff.

Avoid aggressive retry loops. They consume capacity and cannot make deleted or restricted content available.

Choose a plan after a successful test

RapidAPI BASIC currently includes 20 requests/month. API.market has a 7-day trial with 20 API units total. PRO is $9.99/month for 250 requests or API units; ULTRA is $24.99/month for 1,000. Request allowances use hard limits; RapidAPI also displays a separate bandwidth platform fee. Review the actual marketplace billing page before subscribing.

Try one authorized Reel first, then estimate your monthly volume. For a tool that already has a media library or review workflow, this API provides the resolution step; your application owns the import experience, permissions, and any media retention.

Try on RapidAPI · API.market · Postman collection

Questions about integrating your creator or client workflow? Contact cqqrory@gmail.com with your use case and expected monthly volume. Please send no API keys or account credentials.

DEV Community