threads-api

Threads API 技能

为集成 Threads 社交平台的应用开发提供全面的 Meta Threads API 支持。

何时使用此技能

遇到以下情况时，应启用此技能：

• 构建 Threads 集成 - 创建可在 Threads 上发帖或读取内容的应用
• 实现身份验证 - 配置用于访问 Threads API 的 OAuth 流程
• 处理媒体上传 - 将图片、视频或轮播帖子上传到 Threads
• 管理用户内容 - 发布、检索或管理 Threads 帖子
• 获取分析数据 - 检索 Threads 内容的洞察和指标
• 处理 Webhook - 处理来自 Threads 的实时更新
• 排查 API 错误 - 调试身份验证、速率限制或 API 响应问题
• 读取 Threads 个人资料 - 获取用户个人资料数据和帖子

快速参考

身份验证 - 获取访问令牌

// Step 1: Redirect user to authorization endpoint
const authUrl = `https://threads.net/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=threads_basic,threads_content_publish&response_type=code`;

// Step 2: Exchange authorization code for access token
const response = await fetch('https://graph.threads.net/oauth/access_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: 'authorization_code',
    redirect_uri: REDIRECT_URI,
    code: authorizationCode
  })
});

const { access_token } = await response.json();

发布文本帖子

// Create a simple text post
const response = await fetch(`https://graph.threads.net/v1.0/me/threads`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    media_type: 'TEXT',
    text: 'Hello from Threads API! 🎉'
  })
});

const data = await response.json();
console.log('Post ID:', data.id);

发布图片帖子

import requests

# Upload and publish an image
url = "https://graph.threads.net/v1.0/me/threads"
headers = {"Authorization": f"Bearer {access_token}"}

data = {
    "media_type": "IMAGE",
    "image_url": "https://example.com/image.jpg",
    "text": "Check out this image! #API"
}

response = requests.post(url, headers=headers, json=data)
post_id = response.json()["id"]
print(f"Posted image with ID: {post_id}")

发布视频帖子

// Step 1: Create a video container
const container = await fetch(`https://graph.threads.net/v1.0/me/threads`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({
    media_type: 'VIDEO',
    video_url: 'https://example.com/video.mp4',
    text: 'Check out this video!'
  })
});

const { id: containerId } = await container.json();

// Step 2: Publish the container
await fetch(`https://graph.threads.net/v1.0/me/threads_publish`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({ creation_id: containerId })
});

获取用户个人资料

import requests

# Get authenticated user's profile
url = f"https://graph.threads.net/v1.0/me"
headers = {"Authorization": f"Bearer {access_token}"}
params = {
    "fields": "id,username,name,threads_profile_picture_url,threads_biography"
}

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

print(f"Username: {profile['username']}")
print(f"Bio: {profile['threads_biography']}")

获取用户的 Threads 帖子

// Get user's recent threads with pagination
const response = await fetch(
  `https://graph.threads.net/v1.0/me/threads?fields=id,text,timestamp,media_url&limit=25`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data, paging } = await response.json();
data.forEach(thread => {
  console.log(`${thread.timestamp}: ${thread.text}`);
});

// Use paging.next for next page

发布轮播帖子

import requests

# Create a carousel with multiple images
url = "https://graph.threads.net/v1.0/me/threads"
headers = {"Authorization": f"Bearer {access_token}"}

data = {
    "media_type": "CAROUSEL",
    "children": [
        {"media_type": "IMAGE", "image_url": "https://example.com/img1.jpg"},
        {"media_type": "IMAGE", "image_url": "https://example.com/img2.jpg"},
        {"media_type": "IMAGE", "image_url": "https://example.com/img3.jpg"}
    ],
    "text": "Swipe through these images! 📸"
}

response = requests.post(url, headers=headers, json=data)
carousel_id = response.json()["id"]

获取洞察（分析数据）

// Get insights for a specific thread
const threadId = '123456789';
const response = await fetch(
  `https://graph.threads.net/v1.0/${threadId}/insights?metric=views,likes,replies,reposts`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data } = await response.json();
data.forEach(metric => {
  console.log(`${metric.name}: ${metric.values[0].value}`);
});

错误处理模式

import requests

def make_threads_request(url, access_token, method='GET', **kwargs):
    """Robust error handling for Threads API requests"""
    headers = kwargs.pop('headers', {})
    headers['Authorization'] = f"Bearer {access_token}"

    try:
        response = requests.request(method, url, headers=headers, **kwargs)
        response.raise_for_status()
        return response.json()

    except requests.exceptions.HTTPError as e:
        error_data = e.response.json()
        error_code = error_data.get('error', {}).get('code')
        error_msg = error_data.get('error', {}).get('message')

        if error_code == 190:
            raise Exception(f"Invalid access token: {error_msg}")
        elif error_code == 32:
            raise Exception(f"Rate limit exceeded: {error_msg}")
        else:
            raise Exception(f"API Error {error_code}: {error_msg}")

    except requests.exceptions.RequestException as e:
        raise Exception(f"Network error: {str(e)}")

核心概念

访问令牌和权限

• 访问令牌：所有 API 请求都需要 OAuth 2.0 令牌
• 权限范围：定义应用可访问的内容（例如，threads_basic、threads_content_publish、threads_manage_insights）
• 令牌过期：长期令牌（60 天）和用于延长访问期限的刷新令牌

媒体类型

• TEXT：纯文本帖子
• IMAGE：单张图片，可选配说明文字
• VIDEO：单个视频，可选配说明文字
• CAROUSEL：以可滑动格式展示的多张图片或视频

发布流程

1. 创建容器：创建包含内容的媒体容器
2. 发布：发布容器，使其公开显示
3. 两阶段流程：视频和轮播帖子必须经过此流程，以留出处理时间

速率限制

• 速率限制因端点和访问级别而异
• 标准速率限制：每位用户每小时 200 次调用
• 监控响应中的 X-Business-Use-Case-Usage 标头
• 对速率限制错误实施指数退避

Webhook

• 针对提及、回复或新关注者等事件发送实时通知
• 接收通知需要 HTTPS 端点
• 必须验证 Webhook 签名以确保安全

参考文件

此技能在 references/ 中包含完整的文档：

• other.md - 完整的 Threads API 文档，包括：
  • 身份验证和授权流程
  • API 端点参考
  • 请求/响应格式
  • 错误代码和故障排查
  • 最佳实践和指南

需要了解特定 API 端点、参数或高级功能的详细信息时，请使用此技能的参考文件。

使用此技能

初学者

首先了解身份验证流程，这是所有 Threads API 集成的基础。重点了解：

1. 设置 Meta 开发者账户和应用
2. 实现 OAuth 2.0 授权
3. 发起第一个 API 请求以获取用户个人资料
4. 发布一条简单的文本帖子

中级用户

在掌握基础知识后，探索以下内容：

1. 媒体上传（图片和视频）
2. 用于发布多图内容的轮播帖子
3. 用于实时更新的 Webhook 集成
4. 错误处理和重试逻辑
5. 速率限制管理

高级用户

通过以下方式优化集成：

1. 洞察和分析数据
2. 提高效率的批量操作
3. 高级内容排期
4. 自定义 Webhook 事件处理
5. 多账户管理

导航提示

• 快速参考：使用上方的代码示例执行常见任务
• 参考文件：查看 references/other.md，了解完整的 API 文档
• 先完成身份验证：始终先正确设置身份验证
• 在沙盒中测试：开发期间使用 Meta 的测试用户和沙盒环境

常见工作流

完整的帖子发布流程

1. 通过 OAuth 流程获取访问令牌
2. 创建媒体容器（如果使用图片或视频）
3. 等待容器处理完成（适用于视频）
4. 发布容器
5. 获取帖子 ID 和数据洞察

用户数据获取流程

1. 验证用户身份
2. 获取包含所需字段的用户个人资料
3. 使用分页功能获取用户的帖子
4. 处理并显示内容

Webhook 集成流程

1. 设置 HTTPS 端点
2. 注册 Webhook 订阅
3. 验证 Webhook 签名
4. 处理传入事件
5. 返回 200 OK 状态

最佳实践

1. 安全

   • 切勿在客户端代码中暴露访问令牌
   • 始终验证 Webhook 签名
   • 使用环境变量存储敏感数据
   • 在令牌过期前刷新令牌

2. 性能

   • 在适当情况下缓存 API 响应
   • 使用批量请求执行多个操作
   • 对大量结果集实现分页
   • 监控并遵守速率限制

3. 用户体验

   • 向用户提供清晰的错误消息
   • API 调用期间显示加载状态
   • 妥善处理网络故障
   • 仅请求必要的权限

4. 内容发布

   • 上传前验证媒体 URL
   • 检查媒体格式要求
   • 为上传失败添加适当的错误处理
   • 考虑添加替代文本以提升无障碍性

资源

官方文档

• Meta for Developers：https://developers.facebook.com/docs/threads
• API 参考：见 references/other.md

开发者工具

• Meta App Dashboard：配置应用并管理权限
• Graph API Explorer：交互式测试 API 调用
• Webhook Testing：上线前测试 Webhook 端点

故障排除

常见问题

身份验证错误（代码 190）

• 检查访问令牌是否有效
• 确认令牌尚未过期
• 确保权限和范围设置正确

速率限制错误（代码 32）

• 实现指数退避
• 监控 API 使用情况
• 考虑缓存响应

媒体上传失败

• 确认媒体 URL 可公开访问
• 检查文件格式和大小要求
• 确保 media_type 参数设置正确

Webhook 未收到事件

• 确认端点使用 HTTPS
• 检查 Webhook 签名验证
• 确保端点能快速返回 200 OK

备注

• 此技能根据 Meta 官方 Threads API 文档生成
• Threads API 属于 Meta Graph API 系列
• Meta 可能会更新 API 功能和端点；请参阅官方文档了解最新变化
• 某些功能可能需要 Meta 进行额外的应用审核或授予额外权限

更新

如需使用更新后的文档刷新此技能：

1. 访问 https://developers.facebook.com/docs/threads 获取最新信息
2. 使用更新后的配置重新运行文档抓取程序
3. 此技能将使用最新的 API 信息重新构建