# igapi Python API

> PyPI 包名: `igapi-rs`。导入名: `import igapi`。平台入口必须使用 `igapi.android.Client` / `igapi.ios.Client` / `igapi.web.Client`。

## 客户端

- `igapi.android.Client(proxy?: Proxy, danger_accept_invalid_certs?, http1_only?, account?)`
- `igapi.ios.Client(proxy?: Proxy, danger_accept_invalid_certs?, http1_only?, account?)`
- `igapi.web.Client(proxy?: Proxy, danger_accept_invalid_certs?, http1_only?, account?)`
- `await client.login(username: str, password: str)`
- `await web.login(username: str, password: str, two_fa_secret?: str)`
- `await web.verify_two_factor(code: str)`
- `await client.is_logged_in() -> bool`
- `await client.logout() -> None`
- `await client.save_session(path: str) -> None`
- `await client.restore_session(path: str) -> None`
- `client.export_account() -> AccountInfo` — Android/Web；iOS 暂不支持。
- `client.export_account_string() -> str` — Android/Web；iOS 暂不支持。
- 代理必须传 `Proxy` 对象，不再接受裸字符串；推荐 `Proxy(proxy_type=ProxyType.SOCKS5H, host="...", port=1080, username=None, password=None)` 这种关键字参数写法，也可用 `Proxy.http(host, port)`、`Proxy.socks5h(...)` 或 `Proxy.from_url(...)` 构造。
- `ProxyType`: `HTTP` / `HTTPS` / `SOCKS4` / `SOCKS4A` / `SOCKS5` / `SOCKS5H`。Web 客户端支持全部类型；Android/iOS 当前仅支持 `HTTP` / `HTTPS`。普通 HTTP CONNECT 代理即使访问 HTTPS 目标也应使用 `Proxy.http(...)` 或 `http://`。

## 用户 / 媒体 / Feed

- `await igapi.UserApi(client).info(user_id: int) -> User`
- `await igapi.UserApi(client).search(query: str) -> list[User]`
- `await igapi.UserApi(client).id_from_username(username: str) -> int`
- `await igapi.UserApi(web).web_id_from_username(username: str) -> int` — 仅 Web。
- `await igapi.UserApi(client).info_by_username(username: str) -> User`
- `await igapi.MediaApi(client).info(media_id: str) -> Media`
- `await igapi.MediaApi(client).info_by_shortcode(shortcode: str) -> Media`
- `await igapi.FeedApi(client).user(user_id: int, max_id?: str) -> tuple[list[Media], str | None]`
- `await igapi.FeedApi(client).user_all(user_id: int, limit?: int) -> list[Media]`

## 上传 / 发帖

- `await igapi.UploadApi(client).photo(image_data: bytes) -> UploadResult`
- `await igapi.UploadApi(client).configure(upload_id: str, caption?: str, location_id?: int, disable_comments?: bool, hide_like_count?: bool) -> Media`
- `await igapi.UploadApi(web).photo_web(image_data: bytes, width: int, height: int) -> UploadResult` — 仅 Web。
- `await igapi.UploadApi(web).configure_web(upload_id: str, caption?: str, disable_comments?: bool, hide_like_count?: bool) -> Media` — 仅 Web。
- `await igapi.PostApi(web).user_posts(username: str, count?: int, after?: str) -> tuple[list[Media], str | None]`
- `await igapi.PostApi(web).create_photo(image_data: bytes, width: int, height: int, caption?: str, disable_comments?: bool, hide_like_count?: bool) -> Media`
- Rust-only 高级上传 API: `check_status` / `photo_with_progress` / `photos_batch` / `configure_with_progress` / `configure_batch`。Python 暂不绑定，因为涉及 Rust 回调、批量调度和 `UploadStatus` 类型封装。

## Direct

- `await igapi.DirectApi(web).prefetch_tokens() -> WebInitTokens`
- `await igapi.DirectApi(web).fire_init_signals(tokens: WebInitTokens) -> WebInitSignalsResult`
- `await igapi.DirectApi(web).create_group_thread(recipient_users: list[str]) -> str`
- `await igapi.DirectApi(web).create_group_thread_graphql(recipient_users: list[str], text: str) -> SendTextResult`
- `await igapi.DirectApi(web).send_text(recipient_igid: str, text: str) -> SendTextResult`
- `await igapi.DirectApi(web).send_text_to_thread(thread_id: str, text: str) -> SendTextResult`
- `await igapi.DirectApi(client).send_text_broadcast(recipient_users: list[str], text: str) -> SendTextResult` — Android/Web。
- iOS Direct 暂未实现；构造后调用会抛 `TypeError`。

## 账号类型

- `igapi.android.AccountIdentity(username, password, user_id?)`
- `igapi.android.DeviceInfo(android_id, phone_id, uuid, device_id, advertising_id?)`
- `igapi.android.SessionInfo(sessionid, ds_user_id, mid?, authorization?, ig_u_ds_user_id?, ig_intended_user_id?, x_mid?, rur?, raw_cookies?, csrf_token?, public_key?, public_key_id?)`
- `igapi.android.AccountInfo(identity, device, session?, profile_id?)`
- `igapi.android.AccountInfo.parse(account_string)`
- `android_account.to_account_string() -> str`
- `igapi.web.AccountInfo.parse(account_string)`；格式 `username:password||csrf_token|cookies||`
- `igapi.ios.AccountInfo` 目前仅为占位类型，暂不支持恢复。

## 异常映射

- `igapi.TwoFactorRequired` -> 需要 2FA，属性 `.two_factor_info`
- `igapi.ChallengeRequired` -> 需要 Challenge，属性 `.challenge_info`
- `ValueError` -> 密码错误、用户无效、解析失败、无效响应、配置错误
- `PermissionError` -> 未登录、账号锁定、私密账号、Session 过期、需要同意条款
- `KeyError` -> 用户/媒体不存在
- `RuntimeError` -> 速率限制、加密错误、初始化失败、Session 读写失败、未知错误
- `ConnectionError` -> 网络连接失败