ListenHubOpenAPI
API リファレンス

コンテンツ抽出

Web 記事、Twitter/X のプロフィールやツイート、YouTube 動画、WeChat 公式アカウントの記事など、URL からテキストコンテンツを非同期に抽出します。

コンテンツ抽出

任意の URL からテキストコンテンツを非同期に抽出します。URL を送信してタスクを作成し、結果をポーリングで取得します。

対応ソース

X / Twitter

プロフィールページと個別のツイート — 公開アカウントの最近の投稿を取得したり、単一のツイートを文脈ごと抽出したりできます。

YouTube

公開されている YouTube 動画の URL から、文字起こしとメタデータを抽出します。

WeChat 公式アカウント

WeChat 公式アカウントの記事（mp.weixin.qq.com）から本文を抽出します。

Web 記事

公開アクセス可能な任意の Web ページ — 記事本文、メタデータ、参照リンクを抽出します。

ユースケース

  • ポッドキャストの素材収集 -- 記事、ツイート、WeChat 公式アカウントの記事を抽出し、ポッドキャスト生成の入力にします
  • コンテンツ要約 -- summarize を使い、長文の取得と要約生成を 1 回の呼び出しで行います
  • ソーシャルメディアのモニタリング -- 重要なアカウントのツイートを一括抽出します
  • リサーチの集約 -- 複数の URL からコンテンツを収集し、構造化します

抽出タスクを作成する

POST /v1/content/extract

タスクの送信はノンブロッキングです。エンドポイントはリクエストを検証し、クレジットを予約して抽出を開始したうえで、すぐに taskId を返します。結果の取得には タスクステータスを照会する を使います。

リクエスト例：

curl -X POST "https://api.marswave.ai/openapi/v1/content/extract" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "url",
      "uri": "https://example.com/article"
    }
  }'
const response = await fetch('https://api.marswave.ai/openapi/v1/content/extract', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LISTENHUB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      type: 'url',
      uri: 'https://example.com/article',
    },
  }),
});
const data = await response.json();
const taskId = data.data.taskId;
console.log('Task ID:', taskId);
import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/content/extract',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'source': {
            'type': 'url',
            'uri': 'https://example.com/article',
        }
    }
)
data = response.json()
task_id = data['data']['taskId']
print('Task ID:', task_id)

オプション付き（要約 + 最大長）：

summarize: true を指定すると、抽出したテキストが AI 要約に圧縮されます。maxLength を指定すると、返される文字数に上限を設けられます。

curl -X POST "https://api.marswave.ai/openapi/v1/content/extract" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "url",
      "uri": "https://example.com/long-article"
    },
    "options": {
      "summarize": true,
      "maxLength": 5000
    }
  }'
const response = await fetch('https://api.marswave.ai/openapi/v1/content/extract', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LISTENHUB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      type: 'url',
      uri: 'https://example.com/long-article',
    },
    options: {
      summarize: true,
      maxLength: 5000,
    },
  }),
});
const data = await response.json();
console.log(data);
import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/content/extract',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'source': {
            'type': 'url',
            'uri': 'https://example.com/long-article',
        },
        'options': {
            'summarize': True,
            'maxLength': 5000,
        },
    }
)
data = response.json()
print(data)

Twitter/X プロフィール URL（ツイート数の指定）：

# For Twitter/X profile URLs, use the twitter option to control how many tweets to fetch
curl -X POST "https://api.marswave.ai/openapi/v1/content/extract" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "url",
      "uri": "https://x.com/elonmusk"
    },
    "options": {
      "twitter": {
        "count": 50
      }
    }
  }'
const response = await fetch('https://api.marswave.ai/openapi/v1/content/extract', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LISTENHUB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      type: 'url',
      uri: 'https://x.com/elonmusk',
    },
    options: {
      twitter: {
        count: 50,
      },
    },
  }),
});
const data = await response.json();
console.log(data);
import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/content/extract',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'source': {
            'type': 'url',
            'uri': 'https://x.com/elonmusk',
        },
        'options': {
            'twitter': {
                'count': 50,
            },
        },
    }
)
data = response.json()
print(data)

WeChat 公式アカウントの記事：

curl -X POST "https://api.marswave.ai/openapi/v1/content/extract" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "url",
      "uri": "https://mp.weixin.qq.com/s/XXXXXXXXXXXXXXXX"
    }
  }'
const response = await fetch('https://api.marswave.ai/openapi/v1/content/extract', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LISTENHUB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      type: 'url',
      uri: 'https://mp.weixin.qq.com/s/XXXXXXXXXXXXXXXX',
    },
  }),
});
const data = await response.json();
const taskId = data.data.taskId;
import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/content/extract',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'source': {
            'type': 'url',
            'uri': 'https://mp.weixin.qq.com/s/XXXXXXXXXXXXXXXX',
        }
    }
)
data = response.json()
task_id = data['data']['taskId']

リクエストボディ：

フィールド型必須説明
sourceobjectはい抽出元
source.typestringはい"url" を指定します
source.uristringはいコンテンツを抽出する URL
optionsobjectいいえ抽出オプション（デフォルトは {}）
options.summarizebooleanいいえ抽出したテキストの AI 要約を生成します（デフォルト false）
options.maxLengthintegerいいえコンテンツの最大長（文字数、デフォルト 100000、最小 1、最大 500000）
options.twitterobjectいいえTwitter/X 専用オプション
options.twitter.countintegerいいえプロフィール URL から取得するツイート数（1–100、デフォルト 20）

レスポンス例：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "67f6a1b2c3d4e5f6a7b8c9d0"
  }
}

taskId は 24 文字の 16 進数文字列です。下記のステータス照会エンドポイントに渡します。

タスクステータスを照会する

GET /v1/content/extract/{taskId}

status が completed または failed になるまで、このエンドポイントをポーリングします。タスク実行中のレスポンスはステータスのみを含み、抽出したコンテンツは抽出とクレジット精算が完了するまで返されません。

リクエスト例：

curl -X GET "https://api.marswave.ai/openapi/v1/content/extract/67f6a1b2c3d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"
const result = await fetch(`https://api.marswave.ai/openapi/v1/content/extract/${taskId}`, {
  headers: {
    'Authorization': `Bearer ${process.env.LISTENHUB_API_KEY}`,
  },
});
const data = await result.json();
console.log('Status:', data.data.status);
import os
import requests

result = requests.get(
    f'https://api.marswave.ai/openapi/v1/content/extract/{task_id}',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'}
)
data = result.json()
print('Status:', data['data']['status'])

パスパラメータ：

フィールド型説明
taskIdstring作成エンドポイントが返した 24 文字の 16 進数文字列

処理中のレスポンス（status: "processing"）：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "67f6a1b2c3d4e5f6a7b8c9d0",
    "status": "processing",
    "createdAt": 1744200000000
  }
}

タスクが完了するまで、data オブジェクト（抽出したコンテンツ）は返されません。

完了時のレスポンス（status: "completed"）：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "67f6a1b2c3d4e5f6a7b8c9d0",
    "status": "completed",
    "createdAt": 1744200000000,
    "data": {
      "content": "The extracted article text content...",
      "metadata": {
        "title": "Article Title",
        "author": "Author Name"
      },
      "references": [
        "https://example.com/related-article"
      ]
    },
    "credits": 100
  }
}

失敗時のレスポンス（status: "failed"）：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "67f6a1b2c3d4e5f6a7b8c9d0",
    "status": "failed",
    "createdAt": 1744200000000,
    "failCode": 1001,
    "message": "Failed to extract content from URL"
  }
}

レスポンスフィールド：

フィールド型説明
taskIdstringタスク識別子
statusstringprocessing、completed、failed のいずれか
createdAtinteger作成時刻。13 桁のエポックミリ秒タイムスタンプ
dataobject抽出したコンテンツ。status が completed のときのみ返されます
data.contentstring抽出したテキストコンテンツ（summarize: true の場合は要約）
data.metadataobjectタイトルや著者などのページメタデータ
data.referencesarrayコンテンツ内で見つかった参照 URL
creditsinteger消費したクレジット（status が completed のときに返されます）
failCodeintegerエラーコード（status が failed のときに返されます）
messagestringエラーの説明（status が failed のときに返されます）

注意事項

Twitter/X のプロフィール URL：

  • ソース URL が Twitter/X のプロフィール（例：https://x.com/username）の場合、API は最近のツイートを取得します。
  • options.twitter.count で取得するツイート数を指定します（1–100、デフォルト 20）。
  • Twitter 以外の URL では、このオプションは無視されます。

WeChat 公式アカウント：

  • 完全な mp.weixin.qq.com/s/... の記事 URL を使います。
  • 抽出されるコンテンツには、記事の本文とメタデータが含まれます。

タスクのライフサイクル：

ステータス説明
processing抽出処理中です
completedコンテンツの抽出に成功しました
failed抽出に失敗しました -- failCode と message を確認してください

ポーリングの推奨設定：

  • 初回の待機：タスク作成後 5 秒
  • ポーリング間隔：5 秒
  • 標準的な完了時間：URL の複雑さに応じて 10-30 秒

クレジット：

コンテンツ抽出はタスク開始時にクレジットを予約し、コンテンツ長が確定した時点で実際の金額に精算します。完了レスポンスの credits フィールドが最終的な課金額を示します。

ルール詳細
事前控除タスク開始時に少額を予約します
実際の課金抽出したコンテンツの文字数に基づき、maxLength を上限とします
失敗時の返還抽出に失敗した場合、予約したクレジットは全額返還されます

コンテンツ抽出自体に見積もりエンドポイントはありません。最終的な credits の値は、コンテンツ長が確定してから決まります。現在の残高は GET /v1/user/subscription で確認でき、クレジットと機能の対応関係は クレジットと料金 を参照してください。

このページの内容

コンテンツ抽出対応ソースユースケース抽出タスクを作成するタスクステータスを照会する注意事項