igapi 数据类型参考¶

1. 概述¶

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

类型	用途
`User`	Instagram 用户信息，包含 ID、用户名、是否私密等
`Media`	帖子/媒体信息，包含类型、标题、点赞数等
`igapi.android.AccountInfo` / `igapi.web.AccountInfo`	平台账号凭证与 Session 信息，支持序列化与恢复
`igapi.ios.AccountInfo`	iOS 账号信息占位类型；当前不支持 `parse()` 字符串恢复，也不支持通过 `Client(account=...)` 恢复
`UploadProgress`	上传进度保留类型；当前 Python 公共 API 暂不返回，Rust core 进度回调使用
`UploadResult`	上传完成后服务端返回的结果

所有类型均为只读属性（不可直接赋值）。Android/Web 账号信息通过对应平台命名空间下的 AccountInfo.parse() 构造。

2. User¶

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

通过 igapi.UserApi(client).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.android.latest.Client()
    await client.login("your_user", "your_pass")

    # 通过用户 ID 查询
    user_api = igapi.UserApi(client)
    user = await user_api.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，仅在通过 igapi.UserApi(client).info(pk) 精确查询时才有正确数值。需要粉丝数时，请先获取 pk 再单独调用 info()。

3. Media¶

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

通过 igapi.MediaApi(client).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.android.latest.Client()
    await client.login("your_user", "your_pass")

    media_api = igapi.MediaApi(client)
    media = await media_api.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。Android/Web 平台适用于持久化存储账号以避免重复登录；iOS 平台的账号字符串解析和 Client(account=...) 恢复当前暂未实现。

账号字符串格式¶

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

Android 平台：

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

Web 平台：

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

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

类方法¶

`AccountInfo.parse(s)`¶

从当前平台的账号字符串解析 AccountInfo 对象。

参数	类型	默认值	说明
`s`	`str`	—	账号字符串

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

实例方法¶

`to_account_string()`¶

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

属性¶

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

属性名	类型	说明
`username`	`str`	用户名
`password`	`str`	密码（明文存储，注意安全）
`platform`	`str`	平台名称，如 `android` / `web`；iOS 类型暂不支持从字符串恢复
`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` 相同）
`advertising_id`	`str \\| None`	Android 广告 ID，部分移动端请求会作为设备画像字段使用

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

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

示例¶

import asyncio
import igapi
from igapi.android import AccountInfo as AndroidAccountInfo
from igapi.android.latest import Client as AndroidClient
from igapi.web import AccountInfo as WebAccountInfo
from igapi.web.latest import Client as WebClient

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

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

    # 2. 下次从字符串恢复
    account = AndroidAccountInfo.parse(account_str)
    print(account.username)     # "john_doe"
    print(account.platform)     # "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 = AndroidClient(account=account)

    # --- Web 账号 ---

    web_account = WebAccountInfo.parse(
        "<username>:<password>||<csrf_token>|sessionid=<sessionid>; ds_user_id=<user_id>||"
    )
    print(web_account.csrf_token)  # "csrf_token_value"
    web_client = WebClient(account=web_account)

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

asyncio.run(main())

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

5. 平台命名空间¶

Python 用户层不暴露全局 PlatformType / AccountInfo。平台由命名空间表达：

平台	客户端	账号信息
Android	`igapi.android.latest.Client`	`igapi.android.AccountInfo`
iOS	`igapi.ios.latest.Client`	`igapi.ios.AccountInfo`（暂不支持 `parse()` 恢复）
Web	`igapi.web.latest.Client`	`igapi.web.AccountInfo`

不同平台的账号字符串结构不同，必须使用对应平台的 AccountInfo.parse()。当前仅 Android 和 Web 平台支持账号字符串解析与恢复。

6. UploadProgress¶

UploadProgress 描述图片或视频上传过程中的进度快照。当前 Python 公共上传 API 暂未绑定 photo_with_progress / configure_with_progress，因此不会主动返回或回调该类型；它主要对应 Rust core 的进度回调能力，并作为后续 Python 进度回调绑定的保留类型。

属性¶

属性名	类型	说明
`uploaded_bytes`	`int`	已上传字节数
`total_bytes`	`int`	总字节数
`stage`	`str`	当前阶段（见下表）
`percentage`	`float`	上传完成比例，范围 `0.0` 至 `1.0`（`0.5` 表示 50%，显示百分比需乘以 100）

stage 值说明¶

stage 为中文阶段描述字符串，取值如下：

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

实例方法¶

`is_complete()`¶

返回 bool，当 stage 为 "已完成" 时为 True。

示例¶

import asyncio
import igapi

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

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

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

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

    # 当前 Python 上传 API 不接受 progress 回调；该类型用于描述 Rust core 进度回调数据结构。
    result = await igapi.UploadApi(client).photo(image_data)
    print(f"上传完成，upload_id={result.upload_id}")

    # UploadProgress 实例的 repr 形如：
    # UploadProgress(stage='上传中', progress=50.0%)

asyncio.run(main())

7. UploadResult¶

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

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

属性¶

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

示例¶

import asyncio
import igapi

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

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

    result = await igapi.UploadApi(client).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）接口时需要用到，通常由 igapi.UploadApi(client).photo() 内部自动处理，无需手动传递。

8. 类型汇总表¶

类型	构造方式	主要用途
`User`	由 API 方法返回	读取用户公开信息
`Media`	由 API 方法返回	读取帖子内容与统计
平台 `AccountInfo`	`igapi.android.AccountInfo.parse(s)` / `igapi.web.AccountInfo.parse(s)` 或 `client.export_account()`	持久化与恢复登录状态
`UploadProgress`	保留类型 / Rust core 进度回调数据结构	Python 当前公共 API 暂不返回
`UploadResult`	由上传方法返回	获取上传结果标识符

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

igapi 数据类型参考¶

1. 概述¶

2. User¶

属性¶

示例¶

注意事项¶

3. Media¶

属性¶

media_type 值说明¶

示例¶

4. AccountInfo¶

账号字符串格式¶

类方法¶

AccountInfo.parse(s)¶

实例方法¶

to_account_string()¶

属性¶

示例¶

5. 平台命名空间¶

6. UploadProgress¶

属性¶

stage 值说明¶

实例方法¶

is_complete()¶

示例¶

7. UploadResult¶

属性¶

示例¶

8. 类型汇总表¶

相关文档¶

`AccountInfo.parse(s)`¶

`to_account_string()`¶

`is_complete()`¶