APIドキュメント

AIテキスト検出API

TruthScanのAI検出APIをアプリケーションに統合するための完全なドキュメントです。

コードを書かずに試すには、以下のFastAPIエンドポイントをご利用ください： https://detect-text.truthscan.com/docs

認証

TruthScanではAPIアクセスにAPIキーを使用します。APIキーは開発者ポータルのページ上部.

すべてのAPIリクエストにAPIキーを含める必要があります：

{
  "key": "YOUR API KEY GOES HERE"
}

YOUR API KEY GOES HERE を実際のAPIキーに置き換えてください。

WebSocketを使用する場合は、URLにOrganization IDを含める必要があります。Organization IDは開発者ポータルのページ上部.

すべてのWebSocketリクエストにOrganization IDを含める必要があります：

wss://detect-text.truthscan.com/ws/$ORG_ID

$ORG_ID を実際のOrganization IDに置き換えてください。

AI検出

検出

このエンドポイントではテキストを送信してAI検出を行います。精度向上のため200語以上を推奨します。

POST https://detect-text.truthscan.com/detect

閾値

resultスコアは1〜100で返されます。50未満は人間、50〜60はAIの可能性、60以上はAIと判断されます。

他の検出器のスコアは参考値であり、主要なresultスコアほど正確ではありません。

改行

JSON送信時は改行を \n としてエンコードしてください。

リクエスト例

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0,
  "generate_analysis_details": true
}'

入力は30,000語未満である必要があります。

オプションパラメータ

model: 使用するAI検出モデル（デフォルト：'xlm_ud_detector'）
retry_count: 処理失敗時のリトライ回数（デフォルト：0）
generate_analysis_details: 'true'に設定すると詳細AI分析結果が有効になります（デフォルト：'false'）。有効にすると、クエリレスポンスにanalysis_results_statusとanalysis_resultsフィールドが含まれます。

レスポンス例

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

レスポンスにはドキュメントIDが含まれます。処理には通常2〜4秒かかります。

クエリ

ドキュメントIDを使用してステータスと検出結果を取得します。

POST https://detect-text.truthscan.com/query

リクエスト例

curl -X 'POST' \
  'https://detect-text.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "DOCUMENT-ID-GOES-HERE"
}'

レスポンス例

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "result_categories": {
        "advanced": 12,
        "standard": 12
    },
    "status": "done",
    "retry_count": 0
}

結果の解釈

result: テキストがAI生成である可能性を示す0-100のスコア。50未満 = 確実に人間。50-60 = AI の可能性あり。60以上 = 確実にAI。
label: 全体的な判定：'Human'、'AI'、または'Paraphrase'
result_details scores: サードパーティ検出器からの概算スコア：GPTZero、OpenAI、Writer、CrossPlag、CopyLeaks、Sapling、ContentAtScale、ZeroGPT（各0、50、または100）
human: テキストがどの程度人間らしく見えるかを示すサードパーティ検出器スコアの平均
result_categories.advanced: 段階的スコアリングの高度な結果カテゴリ（1-99フォーマット）
result_categories.standard: 標準結果カテゴリ
analysis_results_status: 詳細AI分析のステータス（'pending'、'ready'、'skipped'、またはnull）。'pending'の場合、/queryエンドポイントへの問い合わせを続けてください — 分析はまだバックグラウンドで処理中です。'ready'の場合、analysis_resultsフィールドに完了した分析が含まれます。'skipped'、null、または存在しない場合、このテキストの詳細分析は利用できません。
analysis_results: 詳細AI分析結果（analysis_results_statusが'ready'の場合に利用可能）。含まれるもの：agreement（strong/moderate/weak/disagreement）、confidence（0-100）、keyIndicators（見つかったテキスト指標の配列）、detailedReasoning（説明）、linguisticPatterns（観察された言語パターンの配列）、recommendations（実行可能な項目）。

result値が低いほど人間による文章である可能性が高いことを示します。

クレジット確認

APIキーで残りクレジットを取得します。

GET https://detect-text.truthscan.com/check-user-credits

リクエスト例

curl -X 'GET' \
  'https://detect-text.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

レスポンス例

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

分析結果（非同期詳細分析）

/detectリクエストで'generate_analysis_details'を'true'に設定すると、TruthScanは初期検出完了後にバックグラウンドで詳細AI分析を実行します。初期のクエリレスポンスはステータス'done'で検出結果がすぐに使用可能な状態で返されますが、analysis_results_statusフィールドはまだ'pending'の場合があります。初期結果をすぐに使用し、オプションで詳細分析の完了を待つことができます。

1. 初期結果確定（分析はまだ保留中）

'generate_analysis_details': trueで送信し、ステータス'done'で最初にクエリすると、コア検出結果（result、label、result_details）は準備完了です。ただし、analysis_results_statusが'pending'の場合があります — これは詳細AI分析がまだバックグラウンドで処理中であることを意味します。

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

対応方法

初期検出結果（result、label、result_detailsスコア）はすぐに使用できます。詳細分析も必要な場合は、analysis_results_statusが'pending'から変わるまで、同じドキュメントIDで/queryエンドポイントへの問い合わせを続けてください。

2. 分析結果のポーリングを続ける

同じドキュメントIDで/queryエンドポイントの呼び出しを続けてください。各レスポンスでanalysis_results_statusフィールドを確認してください。'pending'から'ready'に変わると、analysis_resultsオブジェクトにデータが入ります。

curl -X 'POST' \
  'https://detect-text.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
}'

3. 分析完了 — 完全なレスポンス

analysis_results_statusが'ready'になると、analysis_resultsオブジェクトには合意レベル、信頼度、主要指標、詳細な推論、言語パターン、推奨事項を含む完全な詳細AI分析が含まれます。

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "ready",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 78,
            "keyIndicators": [
                "Highly consistent sentence structure throughout",
                "Formulaic transitions between paragraphs",
                "Lack of personal voice or idiosyncratic expressions"
            ],
            "detailedReasoning": "The text exhibits hallmarks of AI-generated content including uniform sentence complexity, predictable paragraph transitions, and an absence of personal stylistic quirks. The vocabulary choices are sophisticated but lack the natural variation typical of human writing.",
            "linguisticPatterns": [
                "Uniform sentence length distribution",
                "Repetitive use of hedging language",
                "Absence of colloquialisms or informal markers"
            ],
            "recommendations": [
                "Cross-reference with the original source if available",
                "Check for consistent writing style across longer documents",
                "Compare with known writing samples from the claimed author",
                "Consider the context in which the text was produced"
            ]
        }
    },
    "result_categories": {
        "advanced": 73,
        "standard": 73
    }
}

分析が利用できない場合

analysis_results_statusが'skipped'、null、または存在しない場合、このテキストの詳細分析は生成されません。これは/detectリクエストで'generate_analysis_details'が'true'に設定されていない場合、または特定の処理シナリオで発生します。初期検出結果を最終的なものとして扱ってください。

{
    "status": "done",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

分析結果フィールド

analysis_results_status: 'pending' = 処理中、'ready' = 結果利用可能、'skipped' / null / 不在 = このテキストでは利用不可
analysis_results.agreement: 詳細分析が初期検出とどの程度一致するか（strong / moderate / weak / disagreement）
analysis_results.confidence: 詳細分析の信頼度スコア（0-100）
analysis_results.keyIndicators: テキスト内で見つかった特定のテキスト指標の配列
analysis_results.detailedReasoning: テキストがそのように分類された理由の2-4文の説明
analysis_results.linguisticPatterns: 観察された言語パターンの配列（例：文構造の一貫性、語彙パターン）
analysis_results.recommendations: テキストの信頼性を理解するための実行可能な推奨事項の配列

文単位AI検出

文単位検出はWebSocketベースで動作します。

必要な手順：

WebSocket接続
イベント受信
document_watch送信
document_id受信
検出リクエスト送信
文単位結果受信
完了イベント受信

WebSocket接続

接続を確立します。

wss://detect-text.truthscan.com/ws/$ORG_ID

コード例

ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");

イベント受信

イベントを監視します。

コード例

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

document_watch送信

検出準備を行います。

コード例

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

document_id受信

IDが返されます。

レスポンス例

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

検出リクエスト送信

IDを使って送信します。

POST https://detect-text.truthscan.com/detect

リクエスト例

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

結果受信

文ごとの結果を受信します。

レスポンス例

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

完了イベントが送信されます。

レスポンス例

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector"
}

例外処理

エラー時はイベントが送信されます。

タイムアウト例

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds."
}

キャンセル

処理を停止できます。

document_haltを送信

レスポンス例

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

エラー

多くのエラーは不正なリクエストによるものです。

主なエラーコード：

コード	内容
400	不正なリクエスト
403	認証エラーまたはクレジット不足
404	リソース未存在
405	無効なメソッド
406	非対応フォーマット
410	削除済み
422	リクエスト形式エラー
429	リクエスト過多
500	サーバーエラー
503	サービス停止中

よくある問題と解決策

認証の問題

"User verification failed" (403)

原因: APIキーが無効または期限切れです

解決策:

APIキーが正しいことを確認してください
アカウントでAPIキーが有効か確認してください
必要に応じてAPIキーを再発行してください

"Not enough credits" (403)

原因: テキスト処理のクレジットが不足しています

解決策:

/check-user-credits で残りクレジットを確認してください
必要に応じてクレジットを追加購入してください
より短いテキスト入力で消費を抑えてください

入力検証の問題

"Input text cannot be empty" (400)

原因: 空または空白のみのテキストが送信されました

解決策:

テキスト入力が空でないことを確認してください
先頭・末尾の空白を削除してください
テキストエンコーディングが正しいか確認してください

"Input email is empty" (400)

原因: URL処理にメールアドレスが不足しています

解決策:

URL送信時に有効なメールアドレスを指定してください
メール形式が正しいか確認してください

処理の問題

"Request timeout" (WebSocket)

原因: ドキュメント処理が長時間（120秒超）かかりました

解決策:

より短いテキストで試してください
サービスの負荷が高い可能性があります
リクエストを再試行してください

ドキュメントステータス "failed"

原因: さまざまな理由で処理に失敗しました

解決策:

入力テキストが最低要件を満たしているか確認してください
サポートされている形式か確認してください
別のモデルで試してください
解決しない場合はサポートにお問い合わせください

WebSocket接続の問題

接続が切断される

原因: ネットワークの問題またはサーバー切断

解決策:

ネットワーク接続を確認してください
再接続ロジックを実装してください
WebSocketのURLが正しいか確認してください

"User not found" (WebSocket)

原因: WebSocket接続のOrganization IDが無効です

解決策:

Organization IDが正しいことを確認してください
ユーザーアカウントが有効か確認してください
必要に応じて再認証してください

サポート

API利用についてはお問い合わせください。

お問い合わせ

APIに関するよくある質問

AI検出APIについて最もよく寄せられる質問への回答です。