媒体 API¶

概述¶

MediaApi 提供 Instagram 媒体内容的查询能力，包括：

根据媒体 ID 获取媒体详细信息
根据帖子 shortcode 获取媒体详细信息

媒体类型涵盖图片（Photo）、视频（Video）和轮播图（Carousel），通过 media_type 字段区分。

通过 client.media() 访问器获取 MediaApi 实例，所有查询操作均在此实例上调用。

import asyncio
from igapi import AccountInfo, Client

account = AccountInfo.parse("username:password||device_info|cookies||")
client = Client(account=account)

# 获取 MediaApi 实例
media_api = client.media()

快速开始¶

以下示例演示两种最常见的使用场景：通过媒体 ID 查询，以及通过帖子 shortcode 查询。

import asyncio
from igapi import AccountInfo, Client

account = AccountInfo.parse("username:password||device_info|cookies||")
client = Client(account=account)
media_api = client.media()

async def main():
    # 场景一：根据媒体 ID 获取媒体信息
    media = await media_api.info(media_id="1234567890123456789")
    print(f"媒体 ID: {media.id}")
    print(f"媒体类型: {media.media_type}")   # 1=图片, 2=视频, 8=轮播
    print(f"标题: {media.caption_text}")
    print(f"点赞数: {media.like_count}")
    print(f"评论数: {media.comment_count}")

    # 场景二：根据 shortcode 获取媒体信息
    # 帖子 URL: https://www.instagram.com/p/BQEil8zBcES/
    # shortcode 即 URL 中 /p/ 后面的部分
    media = await media_api.info_by_shortcode(shortcode="BQEil8zBcES")
    print(f"标题: {media.caption_text}")
    print(f"点赞数: {media.like_count}")

asyncio.run(main())

API 参考¶

`info(media_id)`¶

根据媒体 ID 获取媒体详细信息。

参数¶

参数名	类型	必填	说明
`media_id`	`str`	是	Instagram 媒体的数字 ID 字符串，通常为 18~19 位数字

返回值¶

返回 igapi.Media 对象，包含该媒体的详细信息（详见 Media 类型属性表）。

异常¶

异常类型	触发条件
`KeyError`	媒体 ID 不存在，或帖子已被删除
`PermissionError`	未登录，或帖子属于私密账号且当前账号未互关

示例¶

import asyncio
from igapi import AccountInfo, Client

account = AccountInfo.parse("username:password||device_info|cookies||")
client = Client(account=account)
media_api = client.media()

async def main():
    try:
        media = await media_api.info(media_id="1234567890123456789")
        print(f"标题: {media.caption_text}")
        print(f"点赞: {media.like_count}")
    except KeyError:
        print("媒体不存在或已被删除")
    except PermissionError:
        print("无权限访问，请检查登录状态或账号隐私设置")

asyncio.run(main())

`info_by_shortcode(shortcode)`¶

根据帖子 shortcode 获取媒体详细信息。shortcode 是 Instagram 帖子 URL 中 /p/ 之后、下一个 / 之前的字符串，是每条帖子的唯一标识符。

shortcode 说明¶

Instagram 帖子 URL 的格式如下：

https://www.instagram.com/p/{shortcode}/

示例：

完整 URL	shortcode
`https://www.instagram.com/p/BQEil8zBcES/`	`BQEil8zBcES`
`https://www.instagram.com/p/C1abcDEFghI/`	`C1abcDEFghI`

shortcode 由字母（大小写）和数字组成，通常为 11 位。

参数¶

参数名	类型	必填	说明
`shortcode`	`str`	是	帖子 URL 中 `/p/` 后面的唯一标识符

返回值¶

返回 igapi.Media 对象，包含该媒体的详细信息（详见 Media 类型属性表）。

异常¶

异常类型	触发条件
`KeyError`	shortcode 不存在，或帖子已被删除
`PermissionError`	未登录，或帖子属于私密账号且当前账号未互关

示例¶

import asyncio
from igapi import AccountInfo, Client

account = AccountInfo.parse("username:password||device_info|cookies||")
client = Client(account=account)
media_api = client.media()
shortcode = "BQEil8zBcES"

async def main():
    try:
        media = await media_api.info_by_shortcode(shortcode=shortcode)
        print(f"媒体 ID: {media.id}")
        print(f"标题: {media.caption_text}")
        print(f"评论数: {media.comment_count}")
    except KeyError:
        print(f"shortcode '{shortcode}' 对应的帖子不存在")
    except PermissionError:
        print("无权限访问此帖子")

asyncio.run(main())

Media 类型属性表¶

igapi.Media 对象包含以下属性：

属性名	类型	说明
`id`	`str`	媒体数字 ID，全局唯一，通常为 18~19 位数字字符串
`media_type`	`int`	媒体类型，取值含义见下表
`caption_text`	`str`	帖子标题文本（正文内容）；若未填写标题则为空字符串
`like_count`	`int`	点赞数
`comment_count`	`int`	评论数

media_type 取值说明¶

值	含义
`1`	图片（Photo）
`2`	视频（Video）
`8`	轮播图（Carousel，多张图片或视频）

代码示例¶

根据帖子 URL 获取媒体信息¶

import asyncio
from igapi import AccountInfo, Client

account = AccountInfo.parse("username:password||device_info|cookies||")
client = Client(account=account)
media_api = client.media()

async def main():
    # 已知完整帖子 URL
    url = "https://www.instagram.com/p/BQEil8zBcES/"

    # 获取媒体信息
    media = await media_api.info_by_shortcode(shortcode="BQEil8zBcES")
    print(f"媒体 ID: {media.id}")
    print(f"标题: {media.caption_text[:50]}...")
    print(f"点赞: {media.like_count} | 评论: {media.comment_count}")

asyncio.run(main())

从 URL 中提取 shortcode¶

若要动态处理任意帖子 URL，可以使用字符串操作提取 shortcode：

import asyncio
from igapi import AccountInfo, Client

account = AccountInfo.parse("username:password||device_info|cookies||")
client = Client(account=account)
media_api = client.media()

def extract_shortcode(url: str) -> str:
    """从 Instagram 帖子 URL 中提取 shortcode"""
    # 示例 URL: https://www.instagram.com/p/BQEil8zBcES/
    parts = url.rstrip("/").split("/")
    # /p/ 后面的部分即为 shortcode
    p_index = parts.index("p")
    return parts[p_index + 1]

async def main():
    url = "https://www.instagram.com/p/BQEil8zBcES/"
    shortcode = extract_shortcode(url)
    print(f"提取到 shortcode: {shortcode}")

    media = await media_api.info_by_shortcode(shortcode=shortcode)
    print(f"标题: {media.caption_text}")

asyncio.run(main())

根据媒体类型分类处理¶

不同类型的媒体可能需要不同的处理逻辑，使用 media_type 进行判断：

import asyncio
from igapi import AccountInfo, Client

account = AccountInfo.parse("username:password||device_info|cookies||")
client = Client(account=account)
media_api = client.media()

MEDIA_TYPE_PHOTO    = 1
MEDIA_TYPE_VIDEO    = 2
MEDIA_TYPE_CAROUSEL = 8

async def main():
    media = await media_api.info_by_shortcode(shortcode="BQEil8zBcES")

    if media.media_type == MEDIA_TYPE_PHOTO:
        print("这是一张图片帖子")
    elif media.media_type == MEDIA_TYPE_VIDEO:
        print("这是一个视频帖子")
    elif media.media_type == MEDIA_TYPE_CAROUSEL:
        print("这是一个轮播帖子（包含多张图片或视频）")
    else:
        print(f"未知媒体类型: {media.media_type}")

asyncio.run(main())

错误处理完整示例¶

import asyncio
from igapi import AccountInfo, Client

account = AccountInfo.parse("username:password||device_info|cookies||")
client = Client(account=account)
media_api = client.media()

async def get_media_safe(shortcode: str):
    """安全获取媒体信息，返回 None 表示不可访问"""
    try:
        return await media_api.info_by_shortcode(shortcode=shortcode)
    except KeyError:
        print(f"[警告] shortcode '{shortcode}' 对应的帖子不存在或已删除")
        return None
    except PermissionError:
        print(f"[警告] shortcode '{shortcode}' 无访问权限（私密账号或未登录）")
        return None

async def main():
    shortcodes = ["BQEil8zBcES", "invalid_code", "C1abcDEFghI"]

    for sc in shortcodes:
        media = await get_media_safe(sc)
        if media:
            print(f"{sc}: 点赞 {media.like_count}, 评论 {media.comment_count}")

asyncio.run(main())

注意事项¶

media_id 的格式¶

media_id 是由数字组成的字符串，通常为 18~19 位，类型为 str 而非 int。传参时需传字符串，例如 "1234567890123456789"，不应传入整数。

shortcode 的来源¶

shortcode 仅可从 Instagram 帖子的页面 URL 中获取，格式为 https://www.instagram.com/p/{shortcode}/。shortcode 不等于媒体 ID，两者是不同的标识符：

media_id：纯数字字符串，如 "1234567890123456789"
shortcode：字母数字混合，如 "BQEil8zBcES"

两种方式查询同一条帖子，返回的 Media 对象内容相同。根据已知信息选择调用方式即可。

常见问题¶

Q: 调用 info() 时传入 int 类型的 media_id 会报错吗？

A: media_id 参数类型为 str，应传字符串。传入 int 可能导致类型错误，建议在调用前确保使用 str(media_id) 转换，例如 media_api.info(media_id=str(1234567890123456789))。

Q: 如何判断一条帖子是否包含多张图片？

A: 通过 media.media_type 判断：值为 8 表示轮播图（Carousel），即该帖子包含多张图片或视频。值为 1 表示单张图片，值为 2 表示单个视频。

Q: info() 和 info_by_shortcode() 有性能差异吗？

A: 两者均调用 Instagram 私有 API，底层性能相近。选择哪种方式取决于已知信息：如果手头有 shortcode（例如从帖子 URL 获取），使用 info_by_shortcode()；如果已知 media_id（例如从其他 API 返回数据中获得），使用 info()。

媒体 API¶

概述¶

快速开始¶

API 参考¶

info(media_id)¶

参数¶

返回值¶

异常¶

示例¶

info_by_shortcode(shortcode)¶

shortcode 说明¶

参数¶

返回值¶

异常¶

示例¶

Media 类型属性表¶

media_type 取值说明¶

代码示例¶

根据帖子 URL 获取媒体信息¶

从 URL 中提取 shortcode¶

根据媒体类型分类处理¶

错误处理完整示例¶

注意事项¶

media_id 的格式¶

shortcode 的来源¶

常见问题¶

`info(media_id)`¶

`info_by_shortcode(shortcode)`¶