Media Parsing & Download API

The Media API uses your existing platform USD wallet. Prepay and pay per call, with no monthly fee or media-specific balance expiry. Albums count as one API call; each search or chart page is a separate call. See Media API features and pricing for every rate.

Make your first request

Create a customer API Key in the console API Center and top up your wallet. Open “Media Parsing & Download API” to see available features, run online tests and inspect requests. Online tests are billed at the displayed price.

The base URL is https://www.nextproxy.com/api/customer/v1/media. Send Authorization: Bearer YOUR_NEXTPROXY_API_KEY. Do not use a login token or proxy extraction credential. Keep the key on your server, outside URLs, browser code and public logs.

export MEDIA_BASE_URL='https://www.nextproxy.com/api/customer/v1/media'
export NEXTPROXY_API_KEY='YOUR_NEXTPROXY_API_KEY'

curl "$MEDIA_BASE_URL/catalog" \
  -H "Authorization: Bearer $NEXTPROXY_API_KEY"

GET /catalog is free and returns features, availability, per-call priceMicros, download formats and upload limits. available means the feature is enabled; a particular item must also remain accessible.

GET /balance is free and returns your own shared wallet: availableMicros, reservedMicros, currency and version.

Endpoints and parameters

All paths below are relative to the base URL. All seven paid endpoints require Idempotency-Key, including GET requests.

URLs are limited to 2,048 UTF-8 bytes and supported HTTPS platform links. URL credentials, explicit ports and fragments are rejected. Parameter names are case-sensitive. Do not send duplicate query parameters, extra parameters or unknown JSON fields.

Idempotency and price confirmation

Persist a separate Idempotency-Key for each business operation; a UUID is recommended. Keys contain 8–80 characters: letters, numbers, underscores, hyphens, dots and colons, starting with a letter, number, underscore or hyphen. Replaying the same key and parameters for the same customer returns the original record without another execution or charge. Reusing a key with different parameters returns 409.

Read /catalog for free, then submit the selected endpoint’s confirmed price through X-Expected-Price-Micros. Example prices are not permanent quotes. A new request with a stale quote returns 422 media_price_changed without a charge; refresh and confirm before retrying. Omitting this header uses the current price when the call is created. Amounts are integer microdollar strings: 1 USD = 1,000,000 micros; "150" is $0.00015 and "1500" is $0.0015. Use integer or decimal arithmetic, without rounding each call to cents.

The quoted amount is reserved before execution, charged on success and released on a definite failure. YouTube information and downloads are separate paid operations. For a combined workflow, add the two current operation prices. Downloads do not silently add a paid information request. Existing calls, idempotent replays and refunds retain the original price after a price change.

Social media parsing

curl --get "$MEDIA_BASE_URL/fetch" \
  -H "Authorization: Bearer $NEXTPROXY_API_KEY" \
  -H 'Idempotency-Key: fetch-example-001' \
  -H 'X-Expected-Price-Micros: 150' \
  --data-urlencode 'url=https://www.instagram.com/p/EXAMPLE/'

Replace the placeholder link with accessible content you are authorized to use.

The per-call confirmation price is 500 for Instagram Stories / Highlights, 300 for Rutube / Likee and 150 for other ordinary media in this table. Do not reuse the ordinary Instagram price for Stories or Highlights.

Read data.result. Single media may contain type, download_url, duration and thumbnail_url. Albums may have only items, with no top-level download_url. Iterate over album items and retain useful platform-specific fields; TikTok may also return music or music_url.

YouTube information, search and downloads

Information requests accept YouTube watch, shorts, live, embed and youtu.be links. Search requires both query and page; the query must be nonempty and at most 4,096 UTF-8 bytes, and the page must be an integer starting at 1. Each page is billed separately.

curl --get "$MEDIA_BASE_URL/youtube/info" \
  -H "Authorization: Bearer $NEXTPROXY_API_KEY" \
  -H 'Idempotency-Key: youtube-info-001' \
  --data-urlencode 'url=https://www.youtube.com/watch?v=PVGeM40dABA'

curl --get "$MEDIA_BASE_URL/youtube/search" \
  -H "Authorization: Bearer $NEXTPROXY_API_KEY" \
  -H 'Idempotency-Key: youtube-search-page-001' \
  --data-urlencode 'query=public test film' --data-urlencode 'page=1'

curl "$MEDIA_BASE_URL/youtube/download" \
  -H "Authorization: Bearer $NEXTPROXY_API_KEY" \
  -H 'Idempotency-Key: youtube-download-001' \
  -H 'X-Expected-Price-Micros: 1500' \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://www.youtube.com/watch?v=PVGeM40dABA","format":"720p"}'

All download formats are audio, mp3, m4a, 144p, 240p, 360p, 480p, 720p, 1080p, 1440p and 2160p. A 1440p / 2160p download costs 2500 micros; other downloads cost 1500. Available formats depend on the original video. The information result's filesize is an estimate.

Download directly from the returned media URL, without sending your NextProxy API Key to the media host. YouTube links last approximately 10 minutes; linkExpiresAt is a conservative estimate. Reading a record or replaying the same request does not refresh its link. Obtaining a new link requires an explicit new paid operation.

Deliver audio to a Telegram Bot

This delivers YouTube audio; it does not collect Telegram content. Use a Bot you are authorized to operate. Do not submit a Bot Token.

curl "$MEDIA_BASE_URL/youtube/audio/tg-bot" \
  -H "Authorization: Bearer $NEXTPROXY_API_KEY" \
  -H 'Idempotency-Key: telegram-audio-001' \
  -H 'Content-Type: application/json' \
  --data '{"video_id":"PVGeM40dABA","bot_username":"@your_test_bot"}'

video_id is an 11-character YouTube ID. bot_username includes @ followed by 5–32 letters, numbers or underscores. The default result contains file_id. Add the X-Return-File-Id: false header to receive channel_id / message_id instead. This header accepts only true or false; it is not a JSON field.

Both modes cost $1.50 per 1,000 calls. A file_id belongs to the receiving Bot and must not be reused across Bots or customers. Preserve the original precision of returned identifiers.

Shazam recognition and charts

curl --get "$MEDIA_BASE_URL/shazam/top" \
  -H "Authorization: Bearer $NEXTPROXY_API_KEY" \
  -H 'Idempotency-Key: shazam-world-page-001' \
  --data-urlencode 'country=world' --data-urlencode 'page=1'

curl "$MEDIA_BASE_URL/shazam/identify" \
  -H "Authorization: Bearer $NEXTPROXY_API_KEY" \
  -H 'Idempotency-Key: shazam-identify-001' \
  -F '[email protected]'

Charts accept country=world or a two-letter country code such as US; page is an integer starting at 1. Charts cost 100 micros per request and recognition costs 500 micros.

Upload exactly one nonempty file, at most 50,000,000 bytes, with a filename of at most 255 UTF-8 bytes. Supported extensions are mp4, ogg, m4a and mp3; wav is not supported. Transcode the content when necessary: changing a filename extension is not conversion. Let your HTTP library generate the multipart boundary instead of manually overriding Content-Type.

Responses, records and refunds

Paid requests return persistent call records. HTTP 200 does not guarantee business success. Check data.status before consuming data.result:

{
  "data": {
    "id": "EXAMPLE_REQUEST_ID",
    "status": "succeeded",
    "deliveryStatus": "links_ready",
    "priceMicros": "1500",
    "chargedMicros": "1500",
    "refundedMicros": "0",
    "result": {
      "ok": true,
      "download_url": "https://media.example.invalid/temporary.mp4"
    }
  }
}

The example media URL is not accessible. status is running, succeeded, failed or refunded; failed records have chargedMicros: "0". deliveryStatus distinguishes unverified, metadata_ready, links_ready and telegram_reference_ready. links_ready means a temporary download link has been generated; download it before expiry. telegram_reference_ready means an audio reference is available through the specified Bot.

These free routes return only the authenticated customer's data:

Report empty, corrupted or oversized files and failed downloads using empty_file, expired_link, corrupt_file, too_large, unavailable or download_failed. Reports apply to your own successful delivery records, excluding metadata-only operations. Submitting a report does not automatically issue a refund. Approved refunds return to the platform wallet; a link's normal expiry alone is not automatically a delivery fault.

Common errors

HTTP errors include error.code and error.message. A request that fails during processing can return HTTP 200 with data.status=failed and data.errorCode, without a charge. After a network timeout, retain the original key and parameters. Query the record if you have its ID; otherwise replay the same request with the same key to avoid creating another paid operation.