媒体解析与下载 API

媒体 API 与其他产品共用平台美元钱包，预充值、按次扣费，无月费，媒体产品不设置余额到期时间。图集按一次调用计费，搜索与榜单按每次分页请求计费。完整价格见媒体 API 产品与定价。

开始调用

在控制台 API 中心创建客户 API Key，在钱包充值后，到“媒体解析与下载 API”查看功能开放状态、在线测试及调用记录。在线测试也按页面展示的费用计费。

基础地址为 https://www.nextproxy.com/api/customer/v1/media。请求使用 Authorization: Bearer YOUR_NEXTPROXY_API_KEY；不要使用登录令牌或代理提取凭据。Key 仅保存在自己的服务端，不放在 URL、前端代码或公共日志中。

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 免费返回当前功能、开放状态、单次 priceMicros、下载格式和上传限制。available 表示功能已启用；具体内容能否解析仍取决于内容可用性。

GET /balance 免费查询当前客户的共用钱包，返回 availableMicros、reservedMicros、currency 和 version。

端点与参数

下列路径均相对于基础地址。七个收费端点都要求 Idempotency-Key，包括 GET。

URL 最多 2048 个 UTF-8 字节，仅支持受支持平台的 HTTPS 链接；不接受 URL 用户名、密码、显式端口或片段。参数名区分大小写，不传重复 query、额外参数或未知 JSON 字段。

幂等与费用确认

每个业务操作使用一个独立且持久保存的 Idempotency-Key，建议 UUID。键长为 8–80 字符，可使用字母、数字、下划线、连字符、句点与冒号，首字符只能是字母、数字、下划线或连字符。同一客户、同键、同参数重放返回原记录，不重复执行或扣款；同键不同参数返回 409。

先免费读取 /catalog，再用可选头 X-Expected-Price-Micros 提交对应端点已确认的单次报价。示例数值不是永久报价；新请求的报价不匹配时返回 422 media_price_changed，不会扣款，请刷新目录重新确认。省略该头时按创建调用时的当前售价计费。金额是字符串整数微美元：1 USD = 1,000,000 micros，"150" 表示 $0.00015，"1500" 表示 $0.0015。不要按美分取整；账务计算使用整数或十进制类型。

请求执行前预占报价金额，成功后扣款，明确失败释放预占。YouTube 信息查询与下载分别计费，组合流程按当前两项单价之和计费。下载不会自动增加一次收费信息查询。历史调用、幂等重放和退款均保留创建时的价格，不受后续改价影响。

社交媒体解析

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/'

示例链接是占位内容，使用时替换为你有权访问的有效链接。

Instagram Stories / Highlights 的单次确认价为 500；Rutube、Likee 为 300；其余表中普通媒体为 150。不要把普通帖子的确认价复用于 Stories / Highlights。

结果在 data.result 内。单个媒体可有 type、download_url、duration、thumbnail_url 等字段；图集可能只有 items，没有顶层 download_url。逐项读取图集，保留平台特有字段；TikTok 还可能包含 music 或 music_url。

YouTube 信息、搜索与下载

信息查询支持 YouTube watch、shorts、live、embed 和 youtu.be 链接。搜索必须传入 query 与 page，查询词非空且最多 4096 个 UTF-8 字节；页码为从 1 开始的整数，每一页单独计费。

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"}'

全部下载格式为 audio、mp3、m4a、144p、240p、360p、480p、720p、1080p、1440p、2160p。1440p / 2160p 单次为 2500 micros，其余为 1500。实际可用格式取决于原视频；信息里的 filesize 是估算值。

下载由客户端直接读取返回的媒体链接，不要向媒体域名发送 NextProxy API Key。YouTube 链接有效期约 10 分钟，linkExpiresAt 提供保守估计；读取记录或重放幂等请求不会刷新链接。需要新链接时应明确发起新的付费操作。

音频交付到 Telegram Bot

这是 YouTube 音频交付，不是 Telegram 内容采集。仅向你授权使用的 Bot 发起操作，不需要提交 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 为 11 位 YouTube ID；bot_username 包含 @，后跟 5–32 位字母、数字或下划线。默认返回 file_id；添加请求头 X-Return-File-Id: false 改为返回 channel_id / message_id。该头只接受 true 或 false，不是 JSON 字段。

两种模式均为 $1.50 / 1,000 次。file_id 与接收 Bot 关联，不能跨客户或跨 Bot 复用；保留返回 ID 的原始精度。

Shazam 识曲与榜单

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]'

榜单 country 使用 world 或两位国家代码，例如 US，page 为从 1 开始的整数。榜单单次 100 micros，识曲单次 500 micros。

上传仅允许一个非空 file，最大 50,000,000 字节，文件名最多 255 个 UTF-8 字节。接受 mp4、ogg、m4a、mp3，不接受 wav。实际转码后再上传，只改后缀无效；由 HTTP 库生成 multipart boundary，不要手工覆盖 Content-Type。

响应、记录与退款

收费接口返回持久化调用记录。HTTP 200 不等于业务成功，先检查 data.status，再处理 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"
    }
  }
}

示例结果 URL 不可访问。status 有 running、succeeded、failed、refunded；失败记录 chargedMicros 为 "0"。deliveryStatus 区分 unverified、metadata_ready、links_ready、telegram_reference_ready。links_ready 表示临时下载链接已生成，请在有效期内下载；telegram_reference_ready 表示音频引用已返回，请使用对应 Bot 访问。

以下免费路由只返回当前客户的数据：

空文件、损坏文件、超限文件或下载失败可提交质量报告。reason 支持 empty_file、expired_link、corrupt_file、too_large、unavailable、download_failed。仅自己的成功交付类记录可报告，不适用于纯元信息查询。提交报告不自动退款，审核通过后退回平台钱包；正常超过链接有效期不自动认定为交付故障。

常见错误

HTTP 错误返回 error.code 与 error.message；已进入处理的失败可返回 HTTP 200、data.status=failed 和 data.errorCode，不收费。网络超时时保留原幂等键与参数：已有 ID 就查询记录，没有 ID 就用相同键重放，避免重复新建收费操作。