igapi 数据类型参考¶

1. 概述¶

igapi 模块提供以下五种数据类型，用于描述从 Instagram API 返回或传入的结构化数据：

类型	用途
`User`	Instagram 用户信息，包含 ID、用户名、是否私密等
`Media`	帖子/媒体信息，包含类型、标题、点赞数等
`AccountInfo`	账号凭证与 Session 信息，支持序列化与恢复
`PlatformType`	平台类型枚举，表示 Android / iOS / Web 三个平台
`UploadProgress`	图片/视频上传进度，包含阶段与百分比
`UploadResult`	上传完成后服务端返回的结果

所有类型均为只读属性（不可直接赋值），通过对应 API 方法或 AccountInfo.parse() 构造。

2. User¶

User 表示一个 Instagram 用户的公开信息。

通过 client.user().info(user_id) 或搜索接口返回。

属性¶

属性名	类型	说明
`pk`	`int`	用户数字 ID（永久唯一标识符）
`username`	`str`	用户名（不含 `@`）
`full_name`	`str`	账号昵称/全名
`is_private`	`bool`	是否为私密账号
`profile_pic_url`	`str`	头像图片 URL
`follower_count`	`int`	粉丝数（见注意事项）
`following_count`	`int`	关注数（见注意事项）

示例¶

import asyncio
import igapi

async def main():
    client = igapi.Client()
    await client.login("your_user", "your_pass")

    # 通过用户 ID 查询
    user = await client.user().info(123456789)

    print(user.pk)               # 123456789
    print(user.username)         # "john_doe"
    print(user.full_name)        # "John Doe"
    print(user.is_private)       # False
    print(user.profile_pic_url)  # "https://..."
    print(user.follower_count)   # 1024
    print(user.following_count)  # 512

    print(repr(user))
    # User(pk=123456789, username='john_doe', full_name='John Doe', followers=1024, following=512)

asyncio.run(main())

注意事项¶

follower_count 和 following_count 在搜索接口（search_users）返回的结果中固定为 0，仅在通过 user().info(pk) 精确查询时才有正确数值。需要粉丝数时，请先获取 pk 再单独调用 info()。

3. Media¶

Media 表示一条 Instagram 帖子（图片、视频或轮播）。

通过 client.media().info(media_id) 或 Feed 接口返回。

属性¶

属性名	类型	说明
`id`	`str`	媒体 ID（字符串格式）
`media_type`	`int`	媒体类型（见下表）
`caption_text`	`str`	帖子标题文本，无标题时为空字符串
`like_count`	`int`	点赞数
`comment_count`	`int`	评论数，无法获取时为 `0`

media_type 值说明¶

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

示例¶

import asyncio
import igapi

async def main():
    client = igapi.Client()
    await client.login("your_user", "your_pass")

    media = await client.media().info("3456789012345678901_123456")

    print(media.id)            # "3456789012345678901_123456"
    print(media.media_type)    # 1
    print(media.caption_text)  # "今天天气不错 #sunnyDay"
    print(media.like_count)    # 2048
    print(media.comment_count) # 37

    # 判断媒体类型
    if media.media_type == 1:
        print("这是图片")
    elif media.media_type == 2:
        print("这是视频")
    elif media.media_type == 8:
        print("这是轮播")

    print(repr(media))
    # Media(id='3456789012345678901_123456', type=1, likes=2048, comments=37)

asyncio.run(main())

4. AccountInfo¶

AccountInfo 用于序列化和恢复账号的完整状态，包括用户名、密码、设备标识和 Session Cookie。适用于持久化存储账号以避免重复登录。

账号字符串格式¶

AccountInfo 使用以下紧凑字符串格式存储：

Android 平台：

用户名:密码||android_id;phone_id;uuid;device_id|cookies||

Web 平台：

用户名:密码||csrf_token|cookies||

其中 cookies 段包含 sessionid、ds_user_id、mid 等 Cookie 键值对。

类方法¶

`AccountInfo.parse(s, platform=PlatformType.Android)`¶

从账号字符串解析 AccountInfo 对象。

参数	类型	默认值	说明
`s`	`str`	—	账号字符串
`platform`	`PlatformType`	`PlatformType.Android`	平台类型枚举

返回 AccountInfo。解析失败时抛出 ValueError。

实例方法¶

`to_account_string()`¶

将当前账号信息序列化为字符串，可用于存储或传输。返回与 parse() 兼容的格式字符串。

属性¶

通用属性（Android 与 Web 均有）：

属性名	类型	说明
`username`	`str`	用户名
`password`	`str`	密码（明文存储，注意安全）
`platform`	`PlatformType`	平台类型枚举，如 `PlatformType.Android`
`has_session`	`bool`	是否含有有效的 Session Cookie
`user_id`	`int \\| None`	用户数字 ID，无 Session 时为 `None`
`session_id`	`str \\| None`	Session ID 原始字符串，无 Session 时为 `None`
`mid`	`str \\| None`	Machine ID，来自 Cookie
`ds_user_id`	`int \\| None`	Cookie 中的用户 ID 字段

Android 专属属性（Web 平台下均为 None）：

属性名	类型	说明
`android_id`	`str \\| None`	Android 设备 ID，如 `android-60a691d2387706c4`
`phone_id`	`str \\| None`	Phone UUID
`uuid`	`str \\| None`	设备 UUID
`device_id`	`str \\| None`	Device UUID（通常与 `uuid` 相同）

Web 专属属性（Android 平台下为 None）：

属性名	类型	说明
`csrf_token`	`str \\| None`	CSRF Token，用于 Web 请求签名

示例¶

import asyncio
import igapi
from igapi import PlatformType

async def main():
    # --- Android 账号 ---

    # 1. 首次登录后导出
    client = igapi.Client()
    await client.login("john_doe", "mypassword")
    account = client.export_account()
    account_str = account.to_account_string()
    # 将 account_str 保存到数据库或文件

    # 2. 下次从字符串恢复
    account = igapi.AccountInfo.parse(account_str, PlatformType.Android)
    print(account.username)     # "john_doe"
    print(account.platform)     # PlatformType.Android
    print(account.has_session)  # True
    print(account.user_id)      # 123456789

    # 访问 Android 设备信息
    print(account.android_id)   # "android-60a691d2387706c4"
    print(account.phone_id)     # "7dd70327-354a-4a61-8bb8-79fb3963ebb1"

    # 用账号信息重建客户端（跳过登录）
    client = igapi.Client(account=account)

    # --- Web 账号 ---

    web_account = igapi.AccountInfo.parse(
        "john_doe:mypassword||csrf_token_value|sessionid=xxx; ds_user_id=123||",
        PlatformType.Web
    )
    print(web_account.csrf_token)  # "csrf_token_value"
    web_client = igapi.WebClient(account=web_account)

    print(repr(account))
    # AccountInfo(username='john_doe', platform=PlatformType.Android, has_session=True, user_id=123456789)

asyncio.run(main())

password 以明文形式存储在账号字符串中。请勿将账号字符串存储在不安全的位置（如日志文件、版本控制系统）。

5. PlatformType¶

PlatformType 是平台类型枚举，用于标识 Android、iOS 和 Web 三个平台。

在 AccountInfo.parse() 的 platform 参数以及 AccountInfo.platform 属性中使用。

枚举值¶

枚举成员	整数值	说明
`PlatformType.Android`	`1`	Android 移动端平台（`Client`）
`PlatformType.Ios`	`2`	iOS 移动端平台
`PlatformType.Web`	`3`	Web 浏览器平台（`WebClient`）

类方法¶

`PlatformType.from_value(value)`¶

从整数值构造 PlatformType 枚举。

参数	类型	说明
`value`	`int`	平台整数值（`1`、`2` 或 `3`）

返回对应的 PlatformType。传入无效值时抛出 ValueError。

属性与运算符¶

操作	说明
`PlatformType.Android.value`	返回整数值 `1`
`int(PlatformType.Android)`	转换为整数 `1`
`repr(PlatformType.Android)`	返回字符串 `"PlatformType.Android"`

示例¶

from igapi import PlatformType

# 枚举成员直接引用
platform = PlatformType.Android
print(platform)              # PlatformType.Android
print(platform.value)        # 1
print(int(platform))         # 1
print(repr(platform))        # "PlatformType.Android"

# 从整数值构造
p = PlatformType.from_value(3)
print(p)                     # PlatformType.Web

# 用于 AccountInfo.parse()
import igapi
account = igapi.AccountInfo.parse(account_str, PlatformType.Android)
print(account.platform)      # PlatformType.Android

# 平台类型判断
if account.platform == PlatformType.Android:
    print("这是 Android 账号")
elif account.platform == PlatformType.Web:
    print("这是 Web 账号")

6. UploadProgress¶

UploadProgress 描述图片或视频上传过程中的进度快照，通过上传回调获取。

属性¶

属性名	类型	说明
`uploaded_bytes`	`int`	已上传字节数
`total_bytes`	`int`	总字节数
`stage`	`str`	当前阶段（见下表）
`percentage`	`float`	上传进度，范围 `0.0` 至 `100.0`

stage 值说明¶

值	含义
`"Preparing"`	准备中（初始化上传会话）
`"Uploading"`	上传中（传输文件数据）
`"Configuring"`	配置中（服务端处理媒体）
`"Complete"`	已完成

实例方法¶

`is_complete()`¶

返回 bool，当 stage 为 "Complete" 时为 True。

示例¶

import asyncio
import igapi

def on_progress(progress: igapi.UploadProgress):
    print(f"阶段: {progress.stage}")
    print(f"进度: {progress.percentage:.1f}%")
    print(f"已传: {progress.uploaded_bytes} / {progress.total_bytes} 字节")

    if progress.is_complete():
        print("上传完成！")

async def main():
    client = igapi.Client()
    await client.login("your_user", "your_pass")

    with open("/path/to/photo.jpg", "rb") as f:
        image_data = f.read()

    # 注册回调后执行上传
    result = await client.upload().photo(image_data)

    print(repr(igapi.UploadProgress))
    # UploadProgress(stage='Uploading', progress=50.0%)

asyncio.run(main())

7. UploadResult¶

UploadResult 是上传完成后服务端返回的结果，包含上传 ID 与状态。

通过 client.upload().photo() 等上传方法返回。

属性¶

属性名	类型	说明
`upload_id`	`str`	服务端分配的上传唯一标识符
`status`	`str`	上传状态，通常为 `"ok"`
`offset`	`int`	已确认接收的字节偏移量，断点续传时使用

示例¶

import asyncio
import igapi

async def main():
    client = igapi.Client()
    await client.login("your_user", "your_pass")

    with open("/path/to/photo.jpg", "rb") as f:
        image_data = f.read()

    result = await client.upload().photo(image_data)

    print(result.upload_id)  # "174567890123456789"
    print(result.status)     # "ok"
    print(result.offset)     # 204800

    print(repr(result))
    # UploadResult(upload_id='174567890123456789', status='ok', offset=204800)

asyncio.run(main())

upload_id 在调用发布（configure）接口时需要用到，通常由 upload().photo() 内部自动处理，无需手动传递。

8. 类型汇总表¶

类型	构造方式	主要用途
`User`	由 API 方法返回	读取用户公开信息
`Media`	由 API 方法返回	读取帖子内容与统计
`AccountInfo`	`AccountInfo.parse(s, platform)` 或 `client.export_account()`	持久化与恢复登录状态
`PlatformType`	枚举成员直接引用或 `PlatformType.from_value(n)`	表示平台类型（Android / iOS / Web）
`UploadProgress`	上传回调参数	实时监控上传进度
`UploadResult`	由上传方法返回	获取上传结果标识符

所有类型均支持 repr()，可直接用于调试输出。

igapi 数据类型参考¶

1. 概述¶

2. User¶

属性¶

示例¶

注意事项¶

3. Media¶

属性¶

media_type 值说明¶

示例¶

4. AccountInfo¶

账号字符串格式¶

类方法¶

AccountInfo.parse(s, platform=PlatformType.Android)¶

实例方法¶

to_account_string()¶

属性¶

示例¶

5. PlatformType¶

枚举值¶

类方法¶

PlatformType.from_value(value)¶

属性与运算符¶

示例¶

6. UploadProgress¶

属性¶

stage 值说明¶

实例方法¶

is_complete()¶

示例¶

7. UploadResult¶

属性¶

示例¶

8. 类型汇总表¶

相关文档¶

`AccountInfo.parse(s, platform=PlatformType.Android)`¶

`to_account_string()`¶

`PlatformType.from_value(value)`¶

`is_complete()`¶