StoriesFly: Instagram and TikTok data

storiesfly

StoriesFly API 用の TypeScript クライアントです。HTTP 経由で、公開されている Instagram と TikTok のデータを取得します。Instagram では、プロフィール、ストーリー、ハイライト、投稿、リール、コメント、フォロワー、ハッシュタグ、場所、検索に対応しています。TikTok では、プロフィール、動画、ストーリー、フォロワーとフォロー中の一覧、リポスト、ウォーターマークなしの動画ダウンロードに対応しています。Instagram や TikTok にログインする必要はなく、Cookie やセッションを扱うこともありません。API キーを送信し、リクエストごとに料金を支払います。同じデータは StoriesFly MCP サーバーを通じて ChatGPT と Claude でも利用できます。詳しくはChatGPT と Claude から使う（MCP）をご覧ください。

このパッケージにランタイム依存関係はありません。Node 18 以降が必要です（グローバルの fetch を使用します）。ESM 専用で、型定義も同梱しています。46 個のデータ取得メソッドと無料の account メソッドがあり、すべての戻り値に型が付いています。

インストール

npm install storiesfly

キーを取得する

1. https://storiesfly.com/developers/dashboard で Telegram を使ってサインインします。
2. そこでキーを作成します。新しいアカウントには無料リクエストが 100 回分付与されるため、料金を支払う前にすべてのメソッドを試せます。

キーはサーバー上で保管してください。キーを持っている人は誰でも、残高を使えます。

クイックスタート

現在ストーリーを公開しているアカウント：

import { StoriesFly } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

const { user, stories } = await client.user.stories({ username: "instagram" });

console.log(`${stories.length} stories up from account ${user.id}`);
for (const story of stories) {
  console.log(story.media_type, story.taken_at_iso, story.media_url);
}

知っておくべきこと：

• アカウントは { username } または { id } で指定し、両方を指定することはできません。投稿は { url }、{ code }、または { id } で指定します。型によってこれらが強制されます。
• ID は文字列です。Instagram の ID は 2^53 を超えるため、JSON の数値では丸められてしまいます。
• フィールド名は API が送信する snake_case です。戻り値に含まれない値は null になります。0 や "" にはなりません。
• 戻り値に含まれるメディアリンクは、署名付きの Instagram CDN リンクです。数日以内に期限切れになるため、必要なものは早めにダウンロードしてください。

写真と動画へのリンクを含む投稿：

const post = await client.post.get({ url: "https://www.instagram.com/p/DcyLOLIEdy7/" });

console.log(post.caption, post.likes);
for (const item of post.media) {
  console.log(item.type, item.video_url ?? item.image_url); // one item per slide of a carousel
}

ウォーターマークなしの TikTok 動画と、TikTok アカウントのフォロワー：

const video = await client.tiktok.video({ url: "https://www.tiktok.com/@khaby.lame/video/7697307919943060767" });
console.log(video.caption, video.views, video.video_url); // video_url has no watermark

const profile = await client.tiktok.user.profile({ username: "khaby.lame" });
console.log(profile.followers);

for await (const page of client.paginate(client.tiktok.user.followers, { username: "khaby.lame" }, { maxPages: 2 })) {
  for (const follower of page.users) console.log(follower.username);
}

オプション

new StoriesFly({
  apiKey: "...",       // required, sent as X-Api-Key
  baseUrl: "...",      // default https://storiesfly.com/api/v1
  fetch: myFetch,      // default: the global fetch
  timeoutMs: 60_000,   // per attempt; 0 turns the timeout off
  maxRetries: 2,       // for rate_limited answers; 0 turns retries off
});

すべてのメソッドには、signal（AbortSignal）、timeoutMs、maxRetries、withMeta を指定する最後の引数もあります。

ページネーション

リストを返すメソッドは、next_cursor と has_more を含む 1 ページを返します。client.paginate を使うと、リストを自動的にたどれます。これは非同期イテレーターで、メソッドを呼び出してページを返し、その後、前のページの next_cursor を使って再度呼び出します。has_more が false になるまでこれを繰り返します。

for await (const page of client.paginate(client.user.followers, { username: "instagram" }, { maxPages: 4 })) {
  for (const follower of page.users) console.log(follower.username);
}

• 各ページの取得は 1 回の呼び出しで、1 回分の料金がかかります。大きなアカウントにはページが多数あるため、リスト全体を読み取るのでなければ maxPages を設定してください。
• paginate にはメソッドそのもの（client.user.followers）、そのパラメーター、オプション（maxPages、signal、withMeta）を渡します。パラメーターの cursor を指定すると、すでに取得したページから処理を開始できます。
• ページネーションに対応するのは、cursor を受け取るメソッドだけです。それ以外のメソッドはコンパイラーによって拒否されます。メソッド一覧の Paged 列に対応状況が記載されています。また、エクスポートされている ENDPOINTS の各項目にも paged フラグがあります。
• 手動でページを取得するには、next_cursor を cursor として渡し、ほかのパラメーターはすべて同じにしてください。カーソルは不透明な値です。API から返されていないカーソルを指定すると、bad_request が返ります。
• ページサイズは Instagram の仕様に従い、エンドポイントによって異なります。仕様で固定されているものは 3 つあります。user.posts は 1 ページあたり最大 9 件、user.followers と user.following は最大 25 件を返します。メソッド一覧の Paged 列には、仕様で定められているページサイズが記載されています。

TikTok

TikTok の呼び出しは client.tiktok で行います。アカウントは { username } で指定します。

await client.tiktok.video({ url });                          // one video or photo post, short links too
await client.tiktok.user.profile({ username });              // followers, following, likes, video count
await client.tiktok.user.videos({ username });               // newest first, paged
await client.tiktok.user.stories({ username });              // stories up now
await client.tiktok.user.followers({ username });            // paged
await client.tiktok.user.following({ username });            // paged
await client.tiktok.user.reposts({ username });              // paged

• videos、followers、following、reposts は cursor を受け取り、next_cursor を返すため、client.paginate でページをたどれます。ページサイズは TikTok によって決まり、エンドポイントごとに異なります。
• フォロワーまたはフォロー中のリストを非公開にしているアカウントは、hidden: true を含む空のページを返します。
• 数値が正確でない場合は null になります。ファイルリンクは一時的なため、すぐにファイルを保存してください。
• tiktok.user.videos の後続ページでは、video_url は null になります。個別の動画ファイルを取得するには、tiktok.video を呼び出すか、その動画の url を指定して download を呼び出してください。

ダウンロード

client.download({ url }) は、Instagram の投稿、リール、IGTV、または TikTok の動画や写真投稿のリンク（短縮リンクも可）を受け取り、ファイルリンクを返します。返されるのは、動画（TikTok の場合はウォーターマークなし）、カルーセルや写真投稿のすべての画像、カバー画像、そして TikTok の場合はサウンドトラックです。返されるのはファイルのみです。数値を取得するには post.get または tiktok.video を使用してください。料金は呼び出しごとに固定され、Instagram のリンクは 1,000 件あたり $0.50、TikTok のリンクは 1,000 件あたり $0.20 です。

const { platform, media } = await client.download({ url: "https://www.instagram.com/reel/DdY3MUJCfby/" });
for (const file of media) console.log(file.type, file.url);

ファイルリンクは一時的なため、すぐにダウンロードしてください。client.account() には、ダウンロード料金が download_price_usd として表示されます。

ChatGPT と Claude から使用する（MCP）

同じデータを、コードなしで https://storiesfly.com/mcp を通じて AI アシスタントから利用できます。詳細：https://storiesfly.com/developers/mcp。

• Claude Code の場合：claude mcp add --transport http storiesfly https://storiesfly.com/mcp
• ChatGPT と Claude は同じアドレスに接続し、Telegram でサインインします。

呼び出しの料金：レスポンスメタデータ

呼び出しはパース済みの本文を返します。課金ヘッダーも確認するには、最後の引数として { withMeta: true } を渡します。呼び出しは { data, meta } を返します。

const { data, meta } = await client.user.profile({ username: "instagram" }, { withMeta: true });

console.log(data.followers);
console.log(meta.unitsCharged, meta.balanceRemaining, meta.freeUnitsRemaining);

meta フィールド	ヘッダー	意味
status		HTTP ステータスです。
requestId	X-Request-Id	呼び出しの ID です。サポートに問い合わせる際に、この ID をお知らせください。
unitsCharged	X-Units-Charged	この呼び出しで課金されたユニット数です。無料だった場合、または返金された場合は 0 です。
balanceRemaining	X-Balance-Remaining	呼び出し後の残高です。米ドルで小数点以下 4 桁まで表示されます。文字列のため、浮動小数点数への変換による丸めは発生しません。
freeUnitsRemaining	X-Free-Units-Remaining	残っている無料ユニット数です。
rateLimitLimit	X-RateLimit-Limit	アカウントが 1 秒あたりに送信できるリクエスト数です。
rateLimitRemaining	X-RateLimit-Remaining	現在の 1 秒間に残っているリクエスト数です。

レスポンスに含まれないヘッダーは null になります。メタデータは呼び出しごとに返され、クライアントには保持されません（lastResponse はありません）。そのため、同時に実行される呼び出し同士が数値を上書きすることはありません。paginate で { withMeta: true } を指定すると、各ページについて { data, meta } が返されます。

エラーと課金対象

データを返さない呼び出しはすべて、StoriesFlyError をスローします。message ではなく code を確認してください。

import { StoriesFly, StoriesFlyError } from "storiesfly";

try {
  await client.user.stories({ username: "some_private_account" });
} catch (err) {
  if (!(err instanceof StoriesFlyError)) throw err;

  console.log(err.status);       // HTTP status; 0 when no answer came
  console.log(err.code);         // "private_account"
  console.log(err.requestId);    // quote it to support
  console.log(err.retryAfterMs); // from Retry-After, when the API sent one
  console.log(err.meta?.unitsCharged); // what this failed call was charged
}

その他のフィールド：fields（bad_request の場合、拒否されたパラメーター名）、linkUrl（telegram_required の場合、アカウントを Telegram にリンクするURL）、url（呼び出したURL。キーは含まれません）、body（解析済みのエラー本文）。

回答には課金されます：200、not_found、private_account。パラメーターの誤り、レート制限、残高不足は無料です。また、こちら側の障害は返金されます。err.meta.unitsCharged と X-Units-Charged で、呼び出しにかかった料金がわかります。

ステータス	code	課金	条件
200		はい	データが返されました。
404	not_found	はい	このリクエストに該当するものが見つかりませんでした。
403	private_account	はい	非公開アカウントへの呼び出しが行われました。
400	bad_request	いいえ	パラメーターがないか、無効です。fields に該当するパラメーター名が示されます。
401	unauthorized	いいえ	キーがないか、正しくありません。
402	credits_exhausted	いいえ	クレジットが残っていません。残高をチャージしてください。
403	telegram_required	いいえ	キーに紐づくアカウントが Telegram にリンクされていません。リンク先は linkUrl にあります。
404	unknown_endpoint	いいえ	該当するエンドポイントがありません。
429	rate_limited	いいえ	1秒あたりのリクエスト数が多すぎます。
500	internal_error	返金	こちら側で障害が発生しました。
503	upstream_unavailable	返金	現在データを利用できません。しばらくしてから再試行してください。

クライアントは独自のコードを3つ追加します。応答がなかった場合、status は 0 になります：timeout（timeoutMs 以内に応答がない）、network_error（fetch が失敗。エラーに cause が含まれます）、invalid_response（プロキシのエラーページなど、ドキュメントで定義された形式ではない応答。status と本文が保持されます）。

再試行

• 429 は最大 maxRetries 回（デフォルトは2回）再試行されます。クライアントは API から送信された Retry-After の時間だけ待機します。送信されていない場合は、0.5秒待ってから、徐々に待機時間を延ばします。Retry-After が30秒を超える場合は待機せず、retryAfterMs を設定してすぐにエラーをスローします。
• 402 は再試行されません。再度呼び出しても状況は変わらないためです。
• その他のエラー、タイムアウト、ネットワークエラーは再試行されません。500 または 503 は返金されるため、ご自身で再試行できます。

料金

前払いで、1,000リクエストあたり1.50ドルからです。https://storiesfly.com/developers/pricing をご覧ください。

1ユニットで1リクエストです。リストのページも含め、呼び出しごとに1ユニットかかります。共有リンクの解決には2ユニット、account にはユニットがかかりません。download は呼び出しごとの固定料金で販売され（ダウンロードを参照）、ユニットが残っている場合はそのうち1ユニットを無料で使用できます。無料ユニットは残高より先に消費されます。アカウントごとに1秒あたりのリクエスト数が制限されています。

メソッド

各メソッドは API v1 の呼び出しです。この表は OpenAPI 仕様（openapi.json）から生成され、テストで検証されています。

呼び出し	エンドポイント	単位数	ページ分割	戻り値
client.user.profile()	GET /user/profile	1		認証済みバッジ、自己紹介、リンク、各種件数を含むプロフィール
client.user.about()	GET /user/about	1		国、登録月、以前のユーザー名
client.user.posts()	GET /user/posts	1	はい、最大9ページ	いいね、コメント、再生数、シェア、保存、再投稿数を含む投稿
client.user.reels()	GET /user/reels	1	はい	キャプション、動画、再生数を含むリール
client.user.tagged()	GET /user/tagged	1	はい	アカウントがタグ付けされている投稿
client.user.pinned()	GET /user/pinned	1		プロフィールの上部に固定された投稿
client.user.stories()	GET /user/stories	1		現在公開中のストーリーズ。各動画の長さを含む
client.user.highlights()	GET /user/highlights	1	はい	ハイライトのカバーとタイトル
client.user.followers()	GET /user/followers	1	はい、最大25ページ	フォロワーをページごとに表示
client.user.following()	GET /user/following	1	はい、最大25ページ	フォロー中のアカウントをページごとに表示
client.user.followersSearch()	GET /user/followers/search	1		フォロワーの中からユーザーを検索
client.user.followingSearch()	GET /user/following/search	1		フォロー中のアカウントからユーザーを検索
client.user.reposts()	GET /user/reposts	1	はい	アカウントが再投稿した投稿とリール
client.user.suggested()	GET /user/suggested	1		Instagramがおすすめする類似アカウント
client.post.get()	GET /post	1		1件の投稿：メディアリンク、キャプション、再生数、いいね、コメント、シェア、保存、再投稿数
client.post.comments()	GET /post/comments	1	はい	いいね数と返信数を含むコメント
client.post.commentReplies()	GET /post/comment-replies	1	はい	コメントへの返信
client.post.likers()	GET /post/likers	1		投稿にいいねしたアカウント
client.post.usertags()	GET /post/usertags	1		投稿でタグ付けされたユーザー
client.post.music()	GET /post/music	1		リールで使用されたトラック
client.comment.likers()	GET /comment/likers	1	はい	コメントにいいねしたアカウント
client.story.get()	GET /story	1		リンクまたはIDで指定した1件のストーリーズ
client.highlight.get()	GET /highlight	1		リンクまたはIDで指定したハイライト内のすべてのストーリーズ
client.hashtag.get()	GET /hashtag	1		投稿数を含むハッシュタグ
client.hashtag.posts()	GET /hashtag/posts	1	はい	ハッシュタグの投稿：人気順、新着順、またはリール
client.location.get()	GET /location	1		場所の名前、住所、市区町村、座標
client.location.posts()	GET /location/posts	1	はい	場所がタグ付けされた投稿：人気順または新着順
client.location.search()	GET /location/search	1		名前または地点周辺から場所を検索
client.search.users()	GET /search/users	1	はい	名前またはユーザー名でアカウントを検索
client.search.hashtags()	GET /search/hashtags	1	はい	投稿数を含むハッシュタグを検索
client.search.places()	GET /search/places	1		名前で場所を検索
client.search.music()	GET /search/music	1	はい	タイトルまたはアーティスト名でトラックを検索
client.search.reels()	GET /search/reels	1	はい	テキストに一致するリールを検索
client.search.top()	GET /search/top	1	はい	テキストに一致する人気投稿
client.track.get()	GET /track	1		トラックのタイトル、アーティスト、長さ、音声リンク
client.resolve()	GET /resolve	共有リンクの場合は1または2		投稿、リール、共有リンクをデータに変換
client.shop.storefront()	GET /shop/storefront	1		アカウントのショップ：コレクションと最初の商品
client.shop.products()	GET /shop/products	1	はい	ショップのコレクションに含まれる商品
client.tiktok.video()	GET /tiktok/video	1		透かしなしのTikTok動画1本。再生数、いいね、コメント、シェア数を含む
client.tiktok.user.profile()	GET /tiktok/user/profile	1		フォロワー数、フォロー数、いいね数、動画数を含むTikTokプロフィール
client.tiktok.user.videos()	GET /tiktok/user/videos	1	はい	TikTokアカウントの動画と各種数値をページごとに表示。1ページ目にはファイルリンクを含む
client.tiktok.user.stories()	GET /tiktok/user/stories	1		現在公開中のTikTokストーリーズ
client.tiktok.user.followers()	GET /tiktok/user/followers	1	はい	TikTokのフォロワーをページごとに表示。非公開のリストの場合は空のページが返される
client.tiktok.user.following()	GET /tiktok/user/following	1	はい	TikTokでフォロー中のアカウントをページごとに表示。非公開のリストの場合は空のページが返される
client.tiktok.user.reposts()	GET /tiktok/user/reposts	1	はい	TikTokアカウントが再投稿した動画を、投稿者とともにページごとに表示
client.download()	GET /download	1		リンクで指定したInstagramの投稿またはリール、あるいはTikTok動画のファイル
client.account()	GET /account	0		プラン、残高、無料単位数、使用状況
パラメーターの概要：

• TikTok の呼び出し（tiktok.user.*）には { username } が必要です。tiktok.video と download には { url } が必要です。ページネーションに対応した TikTok の呼び出しには cursor も必要です。
• アカウントの呼び出し（user.*、shop.storefront）には { username } または { id } が必要です。カーソルを使用する呼び出しには cursor も必要です。user.followersSearch と user.followingSearch には q も必要です。
• 投稿の呼び出し（post.*）には { url }、{ code }（リンクの /p/ または /reel/ の後の部分）、または { id } が必要です。post.comments には cursor が必要です。post.commentReplies には comment_id も必要です。
• story.get と highlight.get には { url } または { id } が必要です。
• hashtag.posts には name、sort（top、recent、または reels。ページが変わっても同じ値を使用してください）、および cursor が必要です。location.posts には id、sort（top または recent）、および cursor が必要です。
• location.search には q、または lat と lng が必要です。search.* の呼び出しには、1〜100 文字の q が必要です。
• post.get は投稿全体を返します。media（画像と動画へのリンク。カルーセルの場合はスライドごとに 1 件）、キャプション、投稿者、時刻、および数値が含まれます。これは user.posts、user.reels、hashtag.posts、その他の投稿リストの項目と同じ形式です。また、resolve は投稿リンクに対してこのデータを返します。

ドキュメント

• API ドキュメント（各エンドポイントのページ）：https://storiesfly.com/developers/docs
• OpenAPI 3.1 仕様：https://storiesfly.com/openapi.json（このリポジトリには openapi.json と openapi.yaml としてコピーが含まれています）
• API の変更履歴：https://storiesfly.com/developers/changelog
• このパッケージの変更履歴：CHANGELOG.md
• 使用例：stories.mjs（アカウントのストーリー）、followers.mjs（paginate を使用したフォロワー一覧）、post.mjs（メディアリンクと数値を含む投稿）。STORIESFLY_API_KEY=your_key node examples/stories.mjs instagram を実行してください。

0.x からの移行

1.0 は API v1 向けに書き直されています。以前のメソッドは廃止され、ベース URL が変更され、以前のプランと日次クォータは v1 には存在しません。

0.x	1.0
getStories(username)	user.stories({ username })。{ user, stories } を返します。プロフィールとハイライトは別々の呼び出し（user.profile、user.highlights）になり、それぞれに料金がかかります。
getProfile(username)	user.profile({ username })。id、bio、verified、external_url も取得できます。
getHighlights(id)	ハイライト内のすべてのストーリーを含む highlight.get({ id })。user.highlights はアカウントのハイライト一覧を取得します。
getMedia(url)	post.get({ url })。投稿全体を返します。media には画像と動画のリンク（image_url、video_url。カルーセルの場合はスライドごとに 1 件）が含まれ、キャプション、投稿者、日時、各種カウントも含まれます。
download(url)	1.1 の download({ url }) は、投稿、リール、TikTok 動画のファイルリンクを返します。post.get もメディアリンクを返します。
getTrackerEvents、listTrackedAccounts、addTrackedAccount、removeTrackedAccount、checkShadowban、getOutboundEngagement	API v1 の対象外のため、1.0 には含まれません。

その他の変更点：

• baseUrl のデフォルト値は https://storiesfly.com/api/v1 になりました。bearerToken オプションは廃止されました。v1 ではキーを X-Api-Key に指定する必要があり、ほかの場所では受け付けられません。
• メソッドはリソースごとにグループ化されています。client.user.profile()、client.post.get()、client.search.users() のように呼び出します。すべてのメソッドはパラメーターを 1 つのオブジェクトで受け取ります。
• 返される値には API 独自の snake_case 名が使われ、値がない場合は null になります。fullName は full_name に、profilePicUrl は profile_pic_url に、isPrivate は is_private に、takenAt は taken_at になりました。
• StoriesFlyError には code、requestId、retryAfterMs があります。0.x のフィールドである rateLimit、retryAfterSec、requiresUpgrade、isRateLimited、method は廃止されました。err.code を rate_limited、credits_exhausted などと比較してください。429 は自動的に再試行されます。
• 以前のプラン（DEV、Starter、Growth、Scale、Tracker プラン）、それらの日次クォータ、および 1 分あたり 60 リクエストのバースト制限は廃止されました。v1 ではプリペイド残高からリクエストごとに課金され、新しいアカウントには 100 件の無料リクエストが付与されます。料金をご覧ください。
• 以前のキーは、そのキーに紐づくアカウントを Telegram にリンクすると v1 で使えます。リンクするまでは、v1 は telegram_required を返し、リンク先は err.linkUrl に含まれます。
• トラッカー、シャドウバン、アウトバウンド分析のエンドポイントは引き続き HTTP 経由で応答しますが、1.0 ではラップされません。引き続き利用するには、storiesfly@0 を使い続けるか、自分で呼び出してください。0.x が呼び出す以前の /api/stories、/api/profile、/api/highlights、/api/media、/api/download エンドポイントは、既存の無料キーで 2026-12-31 まで引き続き利用できます。詳細：https://storiesfly.com/developers/docs/legacy。

FAQ

Instagram や TikTok のログインは必要ですか？ いいえ。StoriesFly API キーだけを送信します。管理が必要な Cookie やセッションはありません。

TikTok アカウントのフォロワー一覧を取得できますか？ はい。client.tiktok.user.followers({ username }) はページ単位で一覧を返し、client.paginate でページをたどれます。一覧を非公開にしているアカウントでは、hidden: true を含む空のページが返されます。

ウォーターマークなしで TikTok 動画をダウンロードできますか？ はい。client.tiktok.video({ url }) はウォーターマークなしの video_url を返し、client.download({ url }) は Instagram または TikTok のリンクに対応するファイルリンクを返します。

ChatGPT や Claude から利用できますか？ はい。https://storiesfly.com/mcp の MCP サーバーを通じて利用できます。ChatGPT と Claude からの利用方法（MCP）をご覧ください。

料金体系はどうなっていますか？ プリペイド残高からリクエストごとに課金されます。新しいアカウントには一度だけ 100 件の無料リクエストが付与されます。料金をご覧ください。

提携関係について

これは StoriesFly API のクライアントです。公開データのみを読み取り、非公開アカウントでは private_account が返されます。Instagram または Meta の製品ではなく、両社との提携関係や、両社からの推奨もありません。

開発

npm install
npm test               # clean, build, compile the tests and run them
npm run openapi:check  # validate openapi.json and openapi.yaml, and check that they match
npm run readme:check   # check the method table above against the spec

仕様を更新するには、openapi.json を新しいファイルに置き換え、npm run openapi:sync と npm run readme:sync を実行して、テストを実行します。

ライセンス

MIT。詳細は LICENSE をご覧ください。