教程

Instagram 用户ID查询API使用教程

详细教程：如何通过 SandBase 统一API将 Instagram 用户名转换为用户ID，以及反向查询。包含 curl 和 Python 代码示例，适用于自动化、数据分析和 AI Agent 工作流。

Sophie Lin 作者 Sophie Lin
#instagram #api-tutorial #social-data #user-id #ai-agent #sandbase

Instagram 用户ID查询API使用教程

如果你曾尝试构建 Instagram 自动化工具——无论是粉丝追踪器、数据分析面板，还是社交媒体监控 Agent——你一定遇到过同样的问题：Instagram 的 API 使用数字用户ID，而不是用户名。这意味着在执行任何有用操作之前，你需要一种可靠的方式在用户名和ID之间进行转换。

本教程将展示如何通过 SandBase 统一社交媒体API实现这一功能。我们将涵盖双向转换（用户名 → ID 和 ID → 用户名），提供完整的代码示例，并讨论 AI Agent 和自动化工作流的实际应用场景。

为什么需要 Instagram 用户ID查询

大多数 Instagram 自动化任务需要数字用户ID，而不是人类可读的用户名。原因如下：

  • 粉丝追踪：要监控粉丝数量的变化趋势，你需要目标账号的用户ID来持续查询粉丝列表。
  • 内容排期：自动化工具在内部通过ID引用账号，即使用户输入的是用户名。
  • 数据分析面板：跨账号聚合指标需要稳定的标识符——用户名可以修改，但ID不会变。
  • 跨平台匹配：构建统一社交档案（Instagram + TikTok + YouTube）时，用户ID为每个平台提供稳定的锚点。
  • AI Agent 工作流：监控竞争对手或追踪网红的 Agent 需要程序化的ID解析作为第一步。

问题在于 Instagram 没有提供简单的公开接口来完成这个转换。这正是 SandBase 解决的问题。

SandBase 提供什么

SandBase 提供统一的社交媒体数据API层，覆盖 Instagram、TikTok、抖音、YouTube 等平台。对于 Instagram 用户ID查询，你可以使用两个简洁的接口：

方向接口说明
用户名 → IDinstagram/v3/user-id-by-username通过用户名获取用户ID和个人资料
ID → 用户名instagram/v1/user-id-to-username通过数字用户ID获取用户名

两个接口都返回结构化的 JSON 数据，具有一致的响应格式、完善的错误处理和快速的响应时间。

SandBase Instagram User ID API page

开始使用

准备工作

  1. SandBase 账号（在 sandbase.ai 注册）
  2. 从控制面板获取 API Key
  3. 安装 curl 或 Python（3.7+）

认证方式

所有 SandBase API 调用使用简单的 API Key 请求头：

X-API-Key: your_api_key_here

接口1：用户名查询用户ID

这是最常见的使用场景。你有一个 Instagram 用户名（如 natgeo 或 nike），需要获取对应的数字用户ID。

curl 示例

curl -X GET "https://api.sandbase.ai/instagram/v3/user-id-by-username?username=natgeo" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

响应示例

{
  "status": "success",
  "data": {
    "user_id": "787132",
    "username": "natgeo",
    "full_name": "National Geographic",
    "is_verified": true,
    "is_private": false,
    "profile_pic_url": "https://...",
    "follower_count": 284000000,
    "following_count": 134,
    "media_count": 27500
  }
}

响应不仅包含ID——还有个人资料元数据，对构建面板和 Agent 上下文非常有用。

Python 示例

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.sandbase.ai"

def get_user_id_by_username(username: str) -> dict:
    """将 Instagram 用户名转换为用户ID。"""
    url = f"{BASE_URL}/instagram/v3/user-id-by-username"
    headers = {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    }
    params = {"username": username}

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()


# 使用示例
result = get_user_id_by_username("natgeo")
print(f"用户ID: {result['data']['user_id']}")
print(f"粉丝数: {result['data']['follower_count']}")

接口2：用户ID查询用户名

反向查询适用于你已存储用户ID（来自 webhook、数据库或其他API响应）并需要解析回可读用户名的场景。

curl 示例

curl -X GET "https://api.sandbase.ai/instagram/v1/user-id-to-username?user_id=787132" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

响应示例

{
  "status": "success",
  "data": {
    "user_id": "787132",
    "username": "natgeo",
    "full_name": "National Geographic",
    "is_verified": true,
    "profile_pic_url": "https://..."
  }
}

Python 示例

def get_username_by_id(user_id: str) -> dict:
    """将数字用户ID转换回用户名。"""
    url = f"{BASE_URL}/instagram/v1/user-id-to-username"
    headers = {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    }
    params = {"user_id": user_id}

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()


# 使用示例
result = get_username_by_id("787132")
print(f"用户名: {result['data']['username']}")

实战案例：构建粉丝追踪 Agent

让我们将以上内容整合到一个更实际的场景中。假设你正在构建一个 AI Agent，监控一组竞争对手账号的粉丝数量，并在发生显著变化时发出警报。

import requests
import json
from datetime import datetime

API_KEY = "your_api_key_here"
BASE_URL = "https://api.sandbase.ai"

TRACKED_ACCOUNTS = ["nike", "adidas", "puma", "newbalance"]


def get_user_id_by_username(username: str) -> dict:
    """将 Instagram 用户名转换为用户ID，附带个人资料信息。"""
    url = f"{BASE_URL}/instagram/v3/user-id-by-username"
    headers = {"X-API-Key": API_KEY}
    params = {"username": username}
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()["data"]


def collect_follower_data(usernames: list) -> list:
    """收集一组用户名的粉丝数据。"""
    results = []
    for username in usernames:
        try:
            data = get_user_id_by_username(username)
            results.append({
                "username": data["username"],
                "user_id": data["user_id"],
                "follower_count": data["follower_count"],
                "timestamp": datetime.utcnow().isoformat()
            })
        except requests.HTTPError as e:
            print(f"获取 {username} 数据时出错: {e}")
    return results


def detect_changes(current: list, previous: list, threshold: float = 0.01) -> list:
    """检测粉丝数的显著变化（默认阈值：1%）。"""
    alerts = []
    prev_map = {item["username"]: item["follower_count"] for item in previous}

    for item in current:
        username = item["username"]
        if username in prev_map:
            old_count = prev_map[username]
            new_count = item["follower_count"]
            change_pct = (new_count - old_count) / old_count if old_count > 0 else 0

            if abs(change_pct) >= threshold:
                alerts.append({
                    "username": username,
                    "old_count": old_count,
                    "new_count": new_count,
                    "change_pct": round(change_pct * 100, 2)
                })
    return alerts


# 运行追踪器
if __name__ == "__main__":
    current_data = collect_follower_data(TRACKED_ACCOUNTS)

    # 生产环境中，从数据库加载历史数据
    # previous_data = load_from_db()
    # alerts = detect_changes(current_data, previous_data)

    print(json.dumps(current_data, indent=2, ensure_ascii=False))

这种模式非常适合作为定时任务，或作为更大型的使用 OpenAI SDK 构建的社交监控 Agent 的一部分。

批量处理：多用户名解析

当需要同时解析多个用户名时，添加基本的限流和错误处理：

import time

def batch_resolve_usernames(usernames: list, delay: float = 0.5) -> dict:
    """批量解析用户名到用户ID，含限流处理。"""
    results = {}
    for username in usernames:
        try:
            data = get_user_id_by_username(username)
            results[username] = {
                "user_id": data["data"]["user_id"],
                "full_name": data["data"]["full_name"],
                "follower_count": data["data"]["follower_count"]
            }
        except requests.HTTPError as e:
            results[username] = {"error": str(e)}
        time.sleep(delay)  # 遵守速率限制
    return results


# 解析10个账号
accounts = ["nike", "adidas", "puma", "newbalance", "underarmour",
            "reebok", "asics", "fila", "converse", "vans"]
resolved = batch_resolve_usernames(accounts)

for username, info in resolved.items():
    if "error" not in info:
        print(f"@{username} → ID: {info['user_id']} ({info['follower_count']:,} 粉丝)")

结合其他社交平台API

SandBase 的优势之一是其统一的社交媒体数据处理方式。你可以将 Instagram 用户ID查询与其他平台的API结合使用，构建跨平台用户档案。

SandBase Douyin User Search API page

例如，如果你正在构建一个多平台网红数据库，可以：

  1. 通过 instagram/v3/user-id-by-username 解析 Instagram 用户名 → 用户ID
  2. 查询抖音用户搜索API，找到同一创作者在国内平台的账号
  3. 拉取 TikTok 个人资料数据，获取全球短视频平台信息
  4. 将所有数据合并为统一档案，每个平台使用各自的稳定ID

这种跨平台方法对于处理社交媒体数据的 AI Agent 特别强大，Agent 需要在多个数据源之间建立一致的身份层。

SandBase API 控制面板概览

错误处理最佳实践

以下是常见的错误响应及处理方式：

def safe_lookup(username: str) -> dict | None:
    """带完善错误处理的用户名查询。"""
    try:
        result = get_user_id_by_username(username)
        return result
    except requests.HTTPError as e:
        if e.response.status_code == 404:
            print(f"用户 @{username} 未找到——可能已删除或拼写错误")
        elif e.response.status_code == 429:
            print("触发速率限制——等待后重试")
            time.sleep(60)
            return safe_lookup(username)  # 重试一次
        elif e.response.status_code == 401:
            print("API Key 无效——请检查你的凭证")
        else:
            print(f"未知错误: {e}")
    return None

常见错误码：

  • 404：用户名不存在或账号已删除
  • 429：超出速率限制——实施指数退避策略
  • 401：API Key 无效或已过期
  • 500：服务端错误——短暂延迟后重试

生产环境使用建议

  1. 积极缓存：用户ID不会改变。一旦解析了用户名 → ID的映射，就存储到本地。
  2. 处理用户名变更：用户名可以修改，但ID是永久的。使用ID作为主键。
  3. 非高峰时段批量处理：如果需要解析数百个账号，在低流量时段运行批量任务。
  4. 监控使用量：SandBase 在控制面板中提供使用量分析——关注你的配额使用情况。
  5. 结合 Webhook：对于实时监控，将定期轮询与基于 webhook 的触发器结合使用。

总结

在 Instagram 用户名和用户ID之间进行转换是几乎所有 Instagram 自动化工作流的基础步骤。SandBase 通过两个专注的接口简化了这一过程：

  • instagram/v3/user-id-by-username — 解析用户名到ID + 个人资料信息
  • instagram/v1/user-id-to-username — 解析ID回用户名

无论你是在构建粉丝追踪 Agent、社交媒体数据面板，还是跨平台网红数据库，这些接口都能提供你所需的稳定标识符来构建可靠的自动化系统。

准备开始了吗？注册 SandBase API Key 并尝试上面的示例。如需更高级的工作流，请查看我们关于使用 OpenAI SDK 构建社交监控 Agent 的指南。

猜你喜欢

douyin-user-search-api-tutorial-2026 cover
教程

抖音用户搜索API教程：按关键词查找创作者

学习如何通过SandBase统一API按关键词搜索抖音用户和创作者。包含curl和Python代码示例，适用于KOL发现和社交媒体监控。

Humanize Writing API tutorial cover
教程

Humanize Writing API：让AI文本读起来像人写的

Humanize Writing API 一次调用把 AI 文本改写成自然人味。$0.01/次，无需 prompt，附实测数据和代码示例。

elevenlabs-dubbing-api-tutorial-2026 cover
教程

ElevenLabs 配音API：AI视频翻译教程

学习如何通过 SandBase 使用 ElevenLabs 配音 API，自动将视频和音频内容翻译并重新配音为 29+ 种语言。