mcpField
T
threads

threads

github.com/acedatacloud营销与增长1749 次安装1 天前更新
代码仓库

关于 threads

threads 是通过 curl 和 jq 操作 Threads API 的技能，涵盖发布文本、图片、视频和轮播帖子、查看近期帖子，以及凭据管理与发布限制。

主要功能

  1. 01使用 curl 和 jq 调用 Threads API
  2. 02发布文本和媒体帖子
  3. 03创建轮播帖子
  4. 04列出近期帖子
  5. 05凭据与发布规则说明

适用场景

  1. 01向 Threads 账号发布已确认的帖子
  2. 02分享图片、视频或轮播内容
  3. 03查看近期帖子并获取永久链接

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/acedatacloud/skills --skill threads

安装后在 Claude Code 中输入/threads确认已加载。

详细介绍

使用 curl + jq 调用 Threads API（graph.threads.net）。连接器会注入一个凭据：$THREADS_ACCESS_TOKEN（长期有效的 Threads 访问令牌，具有 threads_basic + threads_content_publish 权限范围）。切勿回显该令牌。

解析一次调用者的 Threads 用户 ID（每次发布都需要）：

ME=$(curl -sS "https://graph.threads.net/v1.0/me?fields=id,username&access_token=$THREADS_ACCESS_TOKEN")
TID=$(echo "$ME" | jq -r .id)
echo "$ME"     # {"id":"<THREADS_USER_ID>","username":"..."}

错误以 JSON 格式返回，包含 error.message / error.code — 原样显示。 401 / OAuthException → 令牌已过期或缺少权限范围；重新连接 Threads 连接器。

发布帖子（两步：创建容器 → 发布）

先与用户确认文本（帖子会以其真实账号发布）。 文本不得超过 500 个字符（表情符号按 UTF-8 字节计数）。

步骤 1 — 创建媒体容器。纯文本（先检查是否超过 500 字节限制）：

TEXT="Shipping one API for AI images → posters, cards, mockups. https://platform.acedata.cloud #AI #API"
[ "$(printf %s "$TEXT" | wc -c)" -le 500 ] || { echo "text exceeds Threads 500-byte limit — shorten it"; }
CID=$(curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads" \
  --data-urlencode "media_type=TEXT" \
  --data-urlencode "text=$TEXT" \
  -d "access_token=$THREADS_ACCESS_TOKEN" | jq -r .id)
echo "container=$CID"

图片帖子 — 添加 media_type=IMAGE + 公开的 image_url（Threads 会在服务器端抓取该 URL，因此图片必须托管在公开服务器上）；视频使用 media_type=VIDEO + video_url：

CID=$(curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads" \
  --data-urlencode "media_type=IMAGE" \
  -d "image_url=https://cdn.acedata.cloud/xxxx.jpg" \
  --data-urlencode "text=caption here" \
  -d "access_token=$THREADS_ACCESS_TOKEN" | jq -r .id)

步骤 2 — 发布容器。文本帖子会立即发布；对于 IMAGE / VIDEO / 轮播容器，必须先等待 ≥30 秒，让 Threads 抓取并处理上传内容 — 过早发布会失败或不返回 ID：

sleep 30   # REQUIRED for IMAGE / VIDEO / carousel; skip for TEXT-only posts
curl -sS -X POST "https://graph.threads.net/v1.0/$TID/threads_publish" \
  -d "creation_id=$CID" -d "access_token=$THREADS_ACCESS_TOKEN" | jq .
# → {"id":"<THREADS_MEDIA_ID>"}

如果 threads_publish 未返回 ID，说明容器尚未准备就绪 — 轮询 GET /v1.0/<CID>?fields=status&access_token=$THREADS_ACCESS_TOKEN，直到 status=FINISHED，然后重试发布。

获取已发布帖子的公开 URL，并提供给用户：

curl -sS "https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>?fields=id,permalink&access_token=$THREADS_ACCESS_TOKEN" | jq -r .permalink

轮播（2–20 项）

为每个子项创建容器，并设置 is_carousel_item=true；然后创建一个 media_type=CAROUSEL 容器，并设置 children=<ID1>,<ID2>,...；最后发布轮播 ID。链接： 添加 link_attachment=<URL>（纯文本帖子，最多 5 个链接）。主题标签：topic_tag=<TAG>。

列出我的近期帖子

curl -sS "https://graph.threads.net/v1.0/$TID/threads?fields=id,text,permalink,timestamp&limit=20&access_token=$THREADS_ACCESS_TOKEN" | jq '.data'

注意事项

  • 500 个字符限制；表情符号按其 UTF-8 字节长度计数。
  • 媒体必须使用公开 URL — Threads 会在服务器端抓取 image_url / video_url； 本地文件无法使用。请先上传到公开主机 / cdn.acedata.cloud。
  • 发布媒体容器前等待约 30 秒（文本帖子会立即发布）；如果 threads_publish 未返回 ID，轮询 GET /<container-id>?fields=status。
  • **速率限制：**每个个人资料每 24 小时最多发布 250 条帖子（轮播计为 1 条）。
  • Threads 令牌与 Facebook / Instagram 令牌不同 — 它们来自 graph.threads.net 上的 Threads OAuth 流程，而不是 graph.facebook.com。

记录输出

成功发布并获取实时永久链接后，调用内置的 publish_artifact 工具一次，让用户能在 My Outputs 中跟踪该内容：

publish_artifact(kind="message", channel="threads", title="<title>", url="<the REAL permalink>", status="delivered")

使用实际返回的 URL — 切勿伪造。每个已发布项目只调用一次， 且仅在确认交付后调用；如果发布失败，则跳过（或使用 status="failed"）。 参见 _shared/artifacts.md。

评论

支持 Markdown