メインコンテンツまでスキップ

よくある質問

全般​

StoryHubフィード とは何ですか？​

StoryHubフィード は、AI を活用したコンテンツ配信 API です。パーソナライズされた、権利クリア済みのコンテンツフィードをアプリケーションに提供します。コンテンツの調達、分析、パーソナライズ配信を処理するため、プロダクト開発に集中できます。

どのような種類のコンテンツが利用できますか？​

フィードには、ライセンス取得済みソースからの記事、ニュース、編集コンテンツが含まれます。すべてのコンテンツは配信に必要な権利がクリアされています。

インテグレーション​

クライアントサイドのコードから API を使用できますか？​

いいえ。API リクエストは必ずバックエンドサーバーを経由してプロキシしてください。クライアントサイドのコード（ブラウザーやモバイルアプリ）で API key を公開することはセキュリティーリスクとなります。

フィード結果のページネーションはどのように行いますか？​

レスポンスの next_cursor フィールドを使用して、次のページを取得します：

GET /v1/feed?scenario=YOUR_SCENARIO_NAME&limit=10&cursor=eyJ...

イベントを送信しないとどうなりますか？​

フィードは引き続き動作しますが、パーソナライゼーションは限定的になります。イベントトラッキングは、コンテンツの関連性を向上させるための主要なシグナルです。少なくとも click イベントの送信を強く推奨します。詳細は 行動イベント をご覧ください。

同じ記事が繰り返し表示されます​

user_id を指定し、click イベントを送信してください。クリック済みコンテンツは既読として以降のフィードから除外されます。

クレジットと請求​

無料のエンドポイントはどれですか？​

ユーザー管理エンドポイント（/v1/users/*）とイベントトラッキング（POST /v1/events）は無料です。完全なリストは クレジット使用量 をご覧ください。

クレジットがなくなるとどうなりますか？​

使用量上限を設定している場合、上限到達時にクレジットを消費するエンドポイントは 402 Usage Limit Exceeded を返します。デフォルトでは従量課金のため、プランの単価で自動課金されます。無料のエンドポイントはいずれの場合も通常どおり動作し続けます。クレジットは各請求サイクルの開始時にリセットされます。

使用量を監視するにはどうすればよいですか？​

StoryHubフィード管理画面のリアルタイム使用量モニターをご確認ください。使用量アラートを設定することもできます。

技術的な質問​

API のレート制限はどのくらいですか？​

レート制限はプランのティアーに応じて異なります（50〜500 リクエスト/秒）。詳細は レート制限 をご覧ください。

コンテンツの鮮度はどの程度ですか？​

コンテンツは継続的にクロールおよび分析されます。新しい記事は通常、公開から数分以内にフィードに表示されます。

サポートされている画像フォーマットは何ですか？​

サムネイルはブラウザーの Accept ヘッダーに基づいて、自動的に WebP または AVIF に変換されます。詳細は 画像配信 をご覧ください。

コンテンツの安全性・信頼性はどのように担保されていますか？​

コンテンツソースの登録時に、AI と人によるチェックを組み合わせて複数の指標で検証しています。どのレベルの信頼性を求めるかは、アルゴリズムの調整時にシナリオ単位で指定できます。

ユーザーとパーソナライゼーション​

事前登録していないユーザーでフィードを取得するとどうなりますか？​

GET /v1/feed でユーザーの自動作成は行われません。未登録の user_id でフィードを取得した場合、フィードは正常に返却されますがパーソナライゼーションは適用されません（汎用フィード）。user_id を指定しない場合も同様に、匿名の汎用フィードが返却されます。

ユーザーを作成するには、以下のいずれかが必要です：

  1. PUT /v1/users/{user_id} で明示的に作成
  2. POST /v1/events で login または session_start イベントを送信（バックグラウンドで自動作成）

詳細は ユーザー管理 をご覧ください。

POST /v1/events でどのイベントタイプがユーザーを自動作成しますか？​

イベントタイプによって挙動が異なります：

イベントタイプユーザー自動作成備考
login○user_id（必須）に基づき作成/更新。metadata.user_attributes のプロパティもマージ
session_start○user_id が含まれている場合に作成/更新。セッション記録も同時に作成
click, impression 等×既に登録済みのユーザーの last_active_at 更新のみ

session_id の仕様を教えてください​

  • 形式: UUID v4 を推奨しますが、任意の非空文字列（最大 256 文字）を受け付けます。ULID や数値 ID など、アプリケーション固有のセッション識別子をそのまま使用できます。
  • 一意性: session_id は 1 つのセッション（= 1 端末 / 1 アプリインスタンスの起動〜終了）に対して一意である必要があります。異なるユーザー間で同じ session_id を共有することはできません。
  • 有効期限: API 側でセッションの有効期限管理は行いません。セッションの区切りはクライアント側の設計にお任せしています。
  • 複数端末: 端末ごとに異なる session_id を持つことに制約はありません。

session_id はセッション管理（開始・終了・継続時間の追跡）、イベント重複排除、利用指標（DAU/MAU 等）の算出に使用されます。パーソナライズのランキングは user_id 単位で行われ、session_id は行動データを正確に記録・整理するための構造化キーとして機能します。

registered_at には何を送ればよいですか？​

アプリケーション側でユーザーが会員登録された日時を ISO 8601 形式（例: 2024-01-15T10:30:00Z）でお送りください。オプショナルのため、取得できない場合は省略しても問題ありません。

tracking_token はどのような役割がありますか？​

tracking_token は以下の用途で利用されます：

  • フィード重複排除 — クリック済み記事を今後のフィードから除外
  • 興味シグナル収集 — パーソナライゼーションの改善
  • 配信効果測定 — Push 通知等のエンゲージメント計測

tracking_token はフィード取得（GET /v1/feed）と Push 候補ファイル（JSONL）に含まれます。一方、GET /v1/contents/{content_id}（単体取得）にはランキング文脈（表示位置・シナリオ等）がないため、tracking_token は含まれません。

エリア指定​

area_names に日本語の駅名を指定する際の注意点はありますか？​

クエリパラメーターに日本語を含む場合は、URL エンコード（パーセントエンコード）が必要です。エンコードされていない場合、インフラ層で不正なリクエストとして拒否されます（400 Bad Request）。

# 方法1: パーセントエンコード
GET /v1/feed?area_names=%E4%BA%8C%E5%AD%90%E7%8E%89%E5%B7%9D&area_level=station

# 方法2: curl の --data-urlencode を使用
curl -G "https://api.feed.storyhub.studio/v1/feed" \
  --data-urlencode "scenario=default_feed" \
  --data-urlencode "area_names=二子玉川" \
  --data-urlencode "area_level=station" \
  -H "Authorization: Bearer YOUR_API_KEY"

なお、駅名の「駅」接尾辞は省略可能です（内部で自動解決されます）。

未登録のエリア名を指定するとどうなりますか？​

未登録の area_name が含まれている場合、そのエリアだけがスキップされ、残りの有効なエリアで記事が取得されます。エラーにはなりません。すべての area_name が未登録だった場合は、エリアフィルターなしとして扱われます。

新しいエリアの追加が必要な場合は、担当のアカウントマネージャーにご依頼ください。

プッシュ通知​

Push 候補は 1 ユーザーあたり何件ですか？​

1 ユーザーあたり 1〜3 件の記事がレコメンドされます。件数は candidates_per_user パラメーター（デフォルト: 1、最大: 3）で指定できます。candidates 配列はスコア降順（先頭が最もスコアの高い記事）で並びます。

Push 候補ファイルのダウンロード URL はどのように使用しますか？​

download_url は GCS の V4 署名付き URL です。認証情報は URL のクエリパラメーターに含まれているため、追加の認証ヘッダーは不要です。そのまま HTTP GET でダウンロードできます。

# download_url をそのまま使用（追加ヘッダー不要）
curl -o candidates.jsonl "DOWNLOAD_URL_FROM_RESPONSE"
  • 有効期限は発行から 1 時間です。
  • 期限切れの場合は GET /v1/push-candidates/{job_id} を再度呼び出すと、新しい URL が発行されます。

サポート​

ここで解決しない質問については、担当のアカウントマネージャーにお問い合わせください。