AIヒューマナイザーAPI：Humanizer API v2と検出API

Academic HumanizerのAIヒューマナイザーAPIには、開発者と機関向けに2つのRESTエンドポイントがあります。文単位の変更付きでhumanizeした文章を返すPOST /api/v2/external/humanizeと、最大100,000文字のAI検出評価を返すPOST /api/v2/external/detectorです。どちらもサーバー側のAPIキーを使い、アカウントと同じクレジット残高を消費します。

この記事では、APIの対象者、認証とアクセス制御の仕組み、各エンドポイントが返す内容、クレジットの計算方法を説明します。完全なリファレンスは/docsにあります。

AI humanizer APIの対象

Webエディターは個々の研究者に適しています。APIは、学術文章を大量に、あるいは自社のインターフェース内で扱う製品やチームに適しています。

• 執筆プラットフォーム：自社のエディター内でhumanizeのステップを提供したい場合。
• LMSや教材ツール：自動的な判定ではなく、人によるレビューの入力の1つとしてAI検出のシグナルが必要な場合。
• 編集・校正サービス：編集者が読む前に、クライアントの原稿に一貫した一次処理をかけたい場合。
• 研究推進部門：助成金申請の文章や報告書をまとめてチェックしたい場合。

学生の課題に関わる用途では、最終的な判断を人が下すように設計してください。検出ツールの出力は検討すべき証拠の1つです。その理由は学生の執筆を疑う前に考えるべきことで説明しています。

認証、IP許可リスト、レート制限

サインインした状態で/apiからキーを作成します。キーは作成時に一度だけ表示され、Academic Humanizerはそのハッシュだけを保存するので、すぐにシークレットマネージャーかサーバーの環境変数にコピーしてください。ブラウザやモバイルのコードには絶対に含めないでください。

キーはX-API-Keyヘッダーで送信します。これがドキュメントで推奨しているヘッダーです。サーバーはAuthorizationヘッダーのベアラートークンとしてもキーを受け付けます。

各リクエストは、テキストが処理される前にいくつかのチェックを通過します。

1. キーのチェックキーが存在して有効であり、その背後のアカウントも有効である必要があります。
2. IP許可リスト制限モードでは、登録したIPまたはCIDR範囲からのリクエストだけが受け付けられます。
3. レート制限キーごとの1秒あたりの上限を超えたリクエストは、HTTP 429で拒否されます。
4. 処理テキストがhumanizeまたは分析され、クレジットが残高と照合されます。
5. 結果の保存結果がアカウントに保存され、JSONとして返されます。

IPアクセスには2つのモードがあります。有効なキーがあればどのIPからでも呼び出せる公開モードと、登録したIPまたはCIDRブロックからのみ呼び出せる制限モードです。固定の送信元アドレスを持つ本番サーバーでは、制限モードを有効にする価値があります。デフォルトのレート制限は1秒あたり10リクエストです。

Humanizeエンドポイント

リクエストボディはJSONで、必須フィールドoriginalContentが1つと、任意フィールドresearchFieldが1つあります。研究分野を送る場合は、対応している名称のいずれかである必要があります。Arts and Humanities、Social Sciences、Business and Economics、Engineering、Natural Sciences、Medical and Health Sciencesです。不要な場合は省略するか、nullを送ってください。

curl -X POST https://academichumanizer.ai/api/v2/external/humanize   -H "Content-Type: application/json"   -H "X-API-Key: YOUR_API_KEY"   -d '{"originalContent": "Paste the paragraph or abstract to humanize here.", "researchField": "Natural Sciences"}'

呼び出しが成功すると、HTTP 201と、次の内容を含むJSONボディが返されます。

• humanizedText：書き換え後の全文。
• changedCount：変更された文の数。
• sentences：文単位のエントリの配列。各エントリには、元の文章における開始・終了オフセット、元の文、humanizeした文、changedフラグが含まれます。配列は空の場合もあります。

保存された結果のIDはX-Humanizer-Idレスポンスヘッダーで返されるので、自社システム内のリクエストを、ユーザーのアカウントに保存された結果と紐づけられます。なお、changedは文が書き換えられたかどうかを示すもので、AI検出の判定ではありません。判定にはDetectorエンドポイントを使ってください。

文のオフセットを使えば、自社のインターフェースで差分を簡単に表示できます。変更された範囲をハイライトし、ユーザーがそれぞれを承認または編集できるようにしましょう。AIによる書き換えは誤りを生じさせたり意味をずらしたりすることがあるため、ユーザーは使う前にすべての出力を確認すべきです。

Detectorエンドポイント

Detectorエンドポイントは、最大100,000文字の必須フィールドtextを1つだけ受け取ります。分析のステータス、文字数、経過時間、文書全体の評価、検出結果、creditUsedを返します。ここでは研究分野は使われません。

よくあるパターンは、まずDetectorを呼び出してどの部分がシグナルを発しているかをユーザーに示し、ユーザーが選んだセクションにだけHumanizeを呼び出すことです。こうすればコストも変更も最小限に抑えられます。

APIクレジットの計算方法

どちらのエンドポイントも、キーを所有するアカウントのクレジットを消費します。2つのエンドポイントでは計算方法が異なります。

Humanizeは500文字ごとに1クレジットで、リクエストごとに切り上げられ、完成した結果が保存されたときにだけ課金されます。Detectorは5,000文字ごとに1クレジットで、切り上げです。残高が不足している場合、リクエストは部分的な結果を返すのではなく、クレジット不足のエラーで失敗します。プランとパックについてはクレジットと料金の仕組みで説明しており、最新の価格は/pricingでご確認いただけます。

処理すべきエラー

エラーボディには機械可読な短いコードが含まれるので、メッセージの文言ではなくコードで分岐してください。

よくある質問

APIキーはどうやって取得しますか？

サインインして/apiを開きます。キーを作成したらすぐにコピーし（一度しか表示されません）、サーバーに保存してください。

キーを使えるサーバーを制限できますか？

はい。IPアクセスを制限モードに切り替え、APIの呼び出しを許可するIPまたはCIDR範囲を登録します。それ以外からのリクエストはHTTP 403で拒否されます。

APIに無料枠はありますか？

APIはWebアプリと同じクレジットを使います。新規アカウントには一度だけ10クレジットが無料で付与され、短い文章いくつかでHumanizeエンドポイントを試すには十分です。

出力はどの検出ツールで確認されていますか？

Academic Humanizerは、Turnitin、GPTZero、ZeroGPT、Copyleaks、Sapling、Originality.aiで検証されています。どのツールでも同じですが、結果は検出ツールによって異なり、特定の結果は保証されません。

Academic Humanizerを組み込む

原稿、アブストラクト、課題をすでに扱っている製品であれば、APIを使ってユーザーをほかのサービスに送ることなく、humanizeのステップや検出チェックを追加できます。まずテスト用のキーで実際の段落をいくつか両方のエンドポイントに通し、本番に移行する前に/docsで完全なリファレンスを読んでください。