threads

curl + jq を使って Threads API（graph.threads.net）を呼び出します。コネクターは認証情報を1つ注入します：$THREADS_ACCESS_TOKEN（threads_basic と threads_content_publish スコープを持つ長期有効な Threads アクセストークン）。このトークンを決して出力しないでください。

呼び出し元の 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":"..."}

エラーは error.message / error.code を含む JSON です。内容をそのまま表示してください。 401 / OAuthException → トークンの有効期限が切れているか、必要なスコープがありません。Threads コネクターを再接続してください。

投稿を公開する（2段階：コンテナーを作成 → 公開）

先にテキストをユーザーに確認してください（ユーザーの実アカウントとして公開されます）。 テキストは 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 はサーバー側で cURL を使って取得するため、公開サーバー上にある必要があります）。動画の場合は 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 で作成し、次に children=<ID1>,<ID2>,... を指定して media_type=CAROUSEL のコンテナーを作成し、最後にカルーセル 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 はサーバー側で cURL を使って image_url／video_url を取得します。ローカルファイルは使えません。まず公開ホストまたは cdn.acedata.cloud にアップロードしてください。
• メディアコンテナーの公開前に約30秒待ってください（テキスト投稿は即時公開されます）。threads_publish が ID を返さない場合は、GET /<container-id>?fields=status をポーリングしてください。
• **レート制限：**プロファイルあたり24時間で公開できる投稿は250件です（カルーセルは1件として数えられます）。
• Threads のトークンは Facebook／Instagram のトークンとは異なります。graph.facebook.com ではなく、graph.threads.net の Threads OAuth フローから取得します。

出力を記録する

公開に成功し、実際に表示されるパーマリンクを取得したら、組み込みの publish_artifact ツールを1回だけ呼び出し、ユーザーが My Outputs で確認できるようにします：

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

実際に返された URL を使用してください。決して捏造しないでください。公開済みの項目ごとに、配信が確認された後に1回だけ呼び出します。公開に失敗した場合は呼び出さないでください（または status="failed" を使用してください）。 _shared/artifacts.md を参照してください。