threads
GitHub通过 Threads API 发布文本、图片、视频或轮播帖子，并读取用户自己的近期贴文。支持跨平台短更新、附件上传及自有内容查看，需使用 BYOC 访问令牌进行认证。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill threads -g -y
SKILL.md
Frontmatter
{
"name": "threads",
"license": "Apache-2.0",
"metadata": {
"author": "acedatacloud",
"version": "1.0"
},
"connections": [
"threads"
],
"description": "Publish text, image, video or carousel posts to your Threads (@threads) account via the official Threads API, and read your own recent posts. Use when the user wants to post to Threads, cross-post a short update \/ thread, attach an image or link, or review their own Threads posts. Auth uses a Threads access token (BYOC). 支持 Threads 文本 \/ 图片 \/ 视频 \/ 轮播发布与自有贴文读取。",
"when_to_use": "Trigger when the user wants to publish a post to their Threads account or\nreview their own recent Threads posts. Threads is Meta's text-first social\napp; the connector stores a Threads access token with threads_content_publish.\nPosting publishes as their real account — confirm the text with the user first.\n",
"allowed_tools": [
"Bash"
]
}
Call the Threads API (graph.threads.net) with curl + jq. The connector
injects one credential: $THREADS_ACCESS_TOKEN (a long-lived Threads access
token with the threads_basic + threads_content_publish scopes). Never echo it.
Resolve the caller's Threads user id once (every publish needs it):
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":"..."}
Errors are JSON with error.message / error.code — show them verbatim.
401 / OAuthException → the token expired or lacks scope; reconnect the
Threads connector.
Publish a post (two-step: create container → publish)
Confirm the text with the user first (it publishes as their real account). Text ≤ 500 characters (emoji counted as UTF-8 bytes).
Step 1 — create a media container. Text-only (guard the 500-byte limit first):
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"
Image post — add media_type=IMAGE + a public image_url (Threads cURLs it
server-side, so it must be on a public server); video uses 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)
Step 2 — publish the container. Text posts publish immediately; for IMAGE / VIDEO / carousel containers you MUST wait ≥30s first so Threads can fetch/process the upload — publishing too early fails or returns no 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>"}
If threads_publish returns no id, the container isn't ready yet — poll
GET /v1.0/<CID>?fields=status&access_token=$THREADS_ACCESS_TOKEN until
status=FINISHED, then retry publish.
Get the public URL of the published post and hand it to the user:
curl -sS "https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>?fields=id,permalink&access_token=$THREADS_ACCESS_TOKEN" | jq -r .permalink
Carousel (2–20 items)
Create each child with is_carousel_item=true, then a media_type=CAROUSEL
container with children=<ID1>,<ID2>,..., then publish the carousel id. Links:
add link_attachment=<URL> (text-only posts, ≤5 links). Topic tag: topic_tag=<TAG>.
List my recent posts
curl -sS "https://graph.threads.net/v1.0/$TID/threads?fields=id,text,permalink,timestamp&limit=20&access_token=$THREADS_ACCESS_TOKEN" | jq '.data'
Gotchas
- 500-char limit; emoji count as their UTF-8 byte length.
- Media must be a public URL — Threads server-side cURLs
image_url/video_url; local files won't work. Upload to a public host / cdn.acedata.cloud first. - Wait ~30s before publishing media containers (text publishes instantly); if
threads_publishdoesn't return an id, pollGET /<container-id>?fields=status. - Rate limit: 250 published posts per 24h per profile (a carousel counts as 1).
- Threads tokens differ from Facebook/Instagram tokens — they come from the
Threads OAuth flow on
graph.threads.net, notgraph.facebook.com.
Record the output
After you successfully publish and obtain the live permalink, call the built-in
publish_artifact tool ONCE so the user can track it in My Outputs:
publish_artifact(kind="message", channel="threads", title="<title>", url="<the REAL permalink>", status="delivered")
Use the real returned URL — never fabricate one. Call it once per published item,
only after delivery is confirmed; skip it (or use status="failed") if publishing failed.
See _shared/artifacts.md.
Version History
- e0220ca Current 2026-07-05 22:56
