用户 API¶

概述¶

UserApi 提供 Instagram 用户信息的查询能力，包括：

根据用户 ID 获取完整用户信息
根据关键词搜索用户
根据用户名查询用户 ID

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

import asyncio
from igapi import AccountInfo, Client

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

# 获取 UserApi 实例
user_api = client.user()

快速开始¶

以下示例演示两种最常见的使用场景：获取指定用户信息，以及搜索用户。

import asyncio
from igapi import AccountInfo, Client

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

async def main():
    # 场景一：根据用户 ID 获取用户信息
    user = await user_api.info(user_id=25025320)
    print(f"用户名: {user.username}")
    print(f"显示名: {user.full_name}")
    print(f"粉丝数: {user.follower_count}")
    print(f"关注数: {user.following_count}")
    print(f"是否私密: {user.is_private}")

    # 场景二：搜索用户
    results = await user_api.search(query="instagram")
    for u in results:
        print(f"  @{u.username}  ({u.full_name})")
        # 注意：搜索结果中 follower_count 为 0，
        # 需调用 user_api.info() 获取真实值

asyncio.run(main())

API 参考¶

`info(user_id)`¶

根据用户 ID 获取完整用户信息。

参数¶

参数名	类型	必填	说明
`user_id`	`int`	是	Instagram 用户的数字 ID

返回值¶

返回 igapi.User 对象，包含该用户的完整信息（详见 User 类型属性表）。

异常¶

异常类型	触发条件
`KeyError`	用户 ID 不存在
`PermissionError`	未登录，或目标账号为私密账号且未互关

示例¶

async def main():
    try:
        user = await user_api.info(user_id=25025320)
        print(f"@{user.username}: {user.follower_count} 粉丝")
    except KeyError:
        print("用户不存在")
    except PermissionError:
        print("无权限访问，请检查登录状态或账号隐私设置")

`search(query)`¶

根据关键词搜索用户，返回匹配的用户列表。

参数¶

参数名	类型	必填	说明
`query`	`str`	是	搜索关键词，如用户名或显示名

返回值¶

返回 list[igapi.User]，列表中每个元素为 igapi.User 对象。

注意：搜索结果中的 follower_count 和 following_count 固定为 0。如需获取真实数值，请对每个用户调用 info(user_id=user.pk)。

异常¶

异常类型	触发条件
`PermissionError`	未登录或 Session 失效

示例¶

async def main():
    results = await user_api.search(query="photographer")
    print(f"共找到 {len(results)} 个用户")
    for user in results:
        print(f"  @{user.username}  {user.full_name}")

`id_from_username(username)`¶

根据用户名查询对应的数字用户 ID。

参数¶

参数名	类型	必填	说明
`username`	`str`	是	Instagram 用户名，不含 `@` 符号前缀

返回值¶

返回 int，即该用户名对应的数字 ID。

异常¶

异常类型	触发条件
`KeyError`	用户名不存在
`PermissionError`	未登录，或目标账号为私密账号且未互关

示例¶

import asyncio
from igapi import AccountInfo, Client

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

async def main():
    try:
        uid = await user_api.id_from_username("instagram")
        print(f"instagram 的用户 ID 是: {uid}")
    except KeyError:
        print("该用户名不存在")

asyncio.run(main())

User 类型属性表¶

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

属性名	类型	说明
`pk`	`int`	用户数字 ID，全局唯一
`username`	`str`	用户名（不含 `@`）
`full_name`	`str`	用户显示名（昵称）
`is_private`	`bool`	是否为私密账号
`profile_pic_url`	`str`	头像图片的 URL
`follower_count`	`int`	粉丝数；搜索结果中固定为 `0`，需调用 `info()` 获取真实值
`following_count`	`int`	关注数；搜索结果中固定为 `0`，需调用 `info()` 获取真实值

代码示例¶

批量获取用户信息¶

import asyncio
from igapi import AccountInfo, Client

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

user_ids = [25025320, 460563723, 1234567890]

async def main():
    for uid in user_ids:
        try:
            user = await user_api.info(user_id=uid)
            print(f"@{user.username} | 粉丝: {user.follower_count} | 关注: {user.following_count}")
        except KeyError:
            print(f"用户 {uid} 不存在，跳过")
        except PermissionError:
            print(f"用户 {uid} 无访问权限，跳过")

asyncio.run(main())

根据用户名查 ID 再获取完整信息¶

import asyncio
from igapi import AccountInfo, Client

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

username = "instagram"

async def main():
    # 第一步：用户名 → 用户 ID
    user_id = await user_api.id_from_username(username)
    print(f"@{username} 的 ID: {user_id}")

    # 第二步：用户 ID → 完整信息
    user = await user_api.info(user_id=user_id)
    print(f"显示名: {user.full_name}")
    print(f"粉丝数: {user.follower_count}")

asyncio.run(main())

搜索并补全 follower_count¶

由于搜索结果不含粉丝数，如需显示真实粉丝数，需对搜索结果中每个用户单独调用 info()：

import asyncio
from igapi import AccountInfo, Client

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

async def main():
    results = await user_api.search(query="travel")

    enriched = []
    for user in results[:5]:  # 只处理前 5 条，避免请求过多
        try:
            full_user = await user_api.info(user_id=user.pk)
            enriched.append(full_user)
        except (KeyError, PermissionError):
            pass  # 跳过无法访问的用户

    for user in enriched:
        print(f"@{user.username}: {user.follower_count} 粉丝")

asyncio.run(main())

错误处理完整示例¶

import asyncio
from igapi import AccountInfo, Client

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

async def get_user_safe(user_id: int):
    """安全获取用户信息，返回 None 表示不可访问"""
    try:
        return await user_api.info(user_id=user_id)
    except KeyError:
        print(f"[警告] 用户 {user_id} 不存在")
        return None
    except PermissionError:
        print(f"[警告] 用户 {user_id} 无访问权限")
        return None

async def main():
    user = await get_user_safe(25025320)
    if user:
        print(f"获取成功: @{user.username}")

asyncio.run(main())

注意事项¶

速率限制¶

Instagram 对 API 调用频率有严格限制，建议：

批量查询时在每次请求之间加入适当延迟（建议 1～3 秒）
避免短时间内对大量用户 ID 发起 info() 请求
短时间内频繁请求可能导致账号被临时限制访问

私密账号¶

对于私密账号（is_private=True），若当前登录账号未与其互相关注，调用 info() 将抛出 PermissionError
搜索结果中可能包含私密账号，但获取其详细信息受到限制

搜索结果中 follower_count 为 0¶

search() 返回的 User 对象中，follower_count 和 following_count 始终为 0，这是 Instagram API 的行为，并非数据错误。如需真实的粉丝/关注数，必须对每个用户单独调用 info(user_id=user.pk)。

常见问题¶

Q: 调用 info() 时出现 PermissionError，是什么原因？

A: 有两种可能：(1) 当前 Session 已失效，请重新登录并更新 AccountInfo；(2) 目标账号为私密账号，且当前账号未关注对方。私密账号仅对互关用户开放完整信息。

Q: 为什么 search() 返回的 follower_count 都是 0？

A: 这是 Instagram 搜索接口的设计限制，搜索结果不包含粉丝数。若需真实粉丝数，请在搜索后对目标用户调用 user_api.info(user_id=user.pk) 补全信息。

Q: id_from_username() 和先搜索再取 pk 有什么区别？

A: id_from_username() 直接通过精确用户名查询 ID，结果更准确且速度更快。search() 是模糊匹配，结果为列表，适合关键词发现。如果已知确切用户名，应优先使用 id_from_username()。

用户 API¶

概述¶

快速开始¶

API 参考¶

info(user_id)¶

参数¶

返回值¶

异常¶

示例¶

search(query)¶

参数¶

返回值¶

异常¶

示例¶

id_from_username(username)¶

参数¶

返回值¶

异常¶

示例¶

User 类型属性表¶

代码示例¶

批量获取用户信息¶

根据用户名查 ID 再获取完整信息¶

搜索并补全 follower_count¶

错误处理完整示例¶

注意事项¶

速率限制¶

私密账号¶

搜索结果中 follower_count 为 0¶

常见问题¶

`info(user_id)`¶

`search(query)`¶

`id_from_username(username)`¶