APIドキュメント

AI音声検出API

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

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

認証

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

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

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

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

AI音声検出

検出（3ステップ）

AI音声検出は以下の手順で実行されます：

署名付きアップロードURLを取得
音声をアップロード
音声を送信して検出

1. 署名付きアップロードURLを取得

APIから署名付きURLを取得し、安全に音声ファイルをアップロードします。

対応形式

MP3, WAV, M4A, FLAC, OGG, MP4

重要

ファイル名にスペースを含めないでください。

GET https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3

リクエスト例

curl -X GET 'https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3' \
--header 'apikey: YOUR API KEY GOES HERE'

レスポンス例

{
  "status": "success",
  "presigned_url": "https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...",
  "file_path": "/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250901-090201_example.mp3"
}

2. 音声をアップロード

presigned_url を使ってPUTでアップロードします。

重要

アップロード時もファイル名のスペースを削除してください。

リクエスト例

curl -X PUT 'https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg, mp4>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

サイズ制限

最小: 1KB
最大: 100MB

アップロード成功時にはステータス200が返されます。

3. 音声を送信して検出

file_path を指定してAI検出を実行します。

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

リクエスト例

curl -X 'POST' \
  'https://detect-audio.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'

FILE_PATH は最初のステップで取得した値です。

任意パラメータ

analyzeUpToSeconds: 最初のN秒を分析（デフォルト: 60秒）
document_type: ドキュメントタイプ（デフォルト: Audio）
email: 処理用メールアドレス

レスポンス例

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

レスポンスには追跡用IDが含まれます。

ステータスと結果取得

/queryエンドポイントで結果を取得します。

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

リクエスト例

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

レスポンス例

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 0.873,
    "result_details": {
        "is_valid": true,
        "message": "processed",
        "original_duration": 123.45,
        "is_truncated": true,
        "truncated_duration": 60.0,
        "mean_ai_prob": 0.873,
        "individual_chunks_ai_prob": [0.81, 0.90, 0.91]
    }
}

結果詳細

is_valid: 音声ファイルの有効性
message: 処理メッセージ
original_duration: 音声の長さ
is_truncated: 切り詰め有無
truncated_duration: 分析時間
mean_ai_prob: AI確率スコア
individual_chunks_ai_prob: チャンク別スコア

status は "pending" / "analyzing" / "done" / "failed" のいずれかです。

クレジット確認

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

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

リクエスト例

curl -X 'GET' \
  'https://detect-audio.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
}

ヘルスチェック

APIの状態を確認します。

GET https://detect-audio.truthscan.com/health

リクエスト例

curl -X 'GET' \
  'https://detect-audio.truthscan.com/health' \
  -H 'accept: application/json'

レスポンス例

{
    "status": "healthy"
}

エラー

多くのエラーは不正なパラメータによるものです。

主なエラーコード：

コード	内容
400	不正なリクエスト
403	認証エラーまたはクレジット不足
404	リソースが存在しません
429	リクエスト過多
500	サーバーエラー

よくある問題

認証エラー

"User verification failed" (403)

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

対処:

APIキーが正しいか確認してください
アカウントでAPIキーが有効か確認してください
APIキーを再発行してみてください

"Not enough credits" (403)

原因: 音声処理に十分なクレジットがありません

対処:

/check-user-credits で残りクレジットを確認してください
必要に応じてクレジットを追加購入してください
analyzeUpToSeconds で短い区間のみ解析し、消費クレジットを減らしてください

入力エラー

"Unsupported file format" (400)

原因: 未対応または無効な音声形式です

対処:

対応形式か確認してください（MP3、WAV、M4A、FLAC、OGG、MP4）
ファイルが破損していないか確認してください
アップロード時の Content-Type ヘッダーを確認してください

"File too large" (400)

原因: ファイルサイズが100MBの上限を超えています

対処:

100MB以下になるよう圧縮または変換してください
アップロード前にファイルサイズを確認してください
可能なら MP3 など効率的な形式をご利用ください

処理エラー

"Audio processing took too long"

原因: 処理が長時間かかったかタイムアウトしました

対処:

より小さいファイルまたは短い長さで試してください
analyzeUpToSeconds で先頭数秒だけ解析してください
サービスに高負荷がかかっていないか確認してください
数分後にリクエストを再試行してください

Status "failed" in /query response

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

対処:

音声が最小要件を満たすか確認してください（1KB〜100MB）
対応形式か確認してください
検出を送信する前にアップロードが完了したか確認してください
解決しない場合はサポートに問い合わせてください

アップロードエラー

"Audio upload failed" (403/400)

原因: 事前署名URLが無効または期限切れ、またはストレージ側の問題です

対処:

事前署名URLは取得後すぐに使用してください（期限切れの可能性があります）
音声形式に合わせて Content-Type ヘッダーが正しいか確認してください
アップロード前にファイル名からスペースを削除してください
期限切れの場合は新しい事前署名URLを取得してください

"Invalid pre-signed URL" (400)

原因: ファイル名にスペースがある、または期限切れまたは破損した事前署名URLです

対処:

事前署名URLを取得する前にファイル名からスペースをすべて削除してください
ファイル名は英数字、ハイフン、アンダースコアのみを使用してください
必要に応じて新しい事前署名URLを生成してください

サポート

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

お問い合わせ

FAQ

AI音声検出APIに関する質問