Moderation API
Moderation API
テキスト 1 件と最大 4 枚の画像を送信すると、その後の処理に使える判定結果が返ります。7 カテゴリそれぞれの 0~1 のスコア、各スコアがしきい値に達したかどうか、そして allow・review・block のいずれかの総合判定です。ユーザーやモデルが作成したコンテンツを対象に、コメントの公開前、プロンプトや参照画像のモデル送信前、回答や生成画像のユーザーへの表示前などの確認に利用できます。
POST https://api.beatapi.io/v1/moderations
リクエストとレスポンスは OpenAI Moderation API に準拠しているため、公式 OpenAI SDK はベース URL と API キーを変更するだけで利用できます。2026-10-13 に、公式 Python SDK(openai 3.29.0)でテキストと画像の動作を確認しています。
どのモデルが処理するか。 model は任意です。model を省略した場合や OpenAI のコンテンツ判定モデル名を指定した場合は、beat-moderation-2.0 が処理します。beat-moderation-1.0 と beat-moderation-vision-1.0 は名前を指定したときだけ処理し、従来の制限(テキスト 1 件、画像 1 枚、またはその両方)と独自のしきい値が適用されます。2026-10-13 より前の名前 beat-moderation-1 と beat-moderation-vision-1 も引き続き従来のモデルに届きます。レスポンスの model に実際に処理したモデルが示されます。
呼び出しが失敗した場合、判定は行われていません。タイムアウト、4xx、503 などのエラーを「許可」とみなさないでください。コンテンツの公開・送信を保留するか、再試行してください。
Beat Moderation 2.0
beat-moderation-2.0 は既定のモデルです。1 回の呼び出しで、テキスト 1 件と最大 4 枚の画像をまとめて判定します。いずれかが該当すればそのカテゴリが成立するため、問題のない画像が有害なキャプションを隠すことも、問題のないキャプションが有害な画像を隠すこともありません。エンドポイント、リクエストとレスポンスの形式は従来のモデルと同じです。テキストのみ、またはテキストと画像を送信できます。
入力
- テキスト 1 件と最大 4 枚の画像。 テキスト要素は最大 1 つで 8,000 文字まで、
image_url要素は最大 4 つです。 - リンクまたは埋め込み。 画像は、BeatAPI が取得する公開アクセス可能な
http(s)リンク(2,048 文字以内)、または base64 の data URL で指定します。 - PNG、JPEG、WebP、GIF(最初のフレーム)、1 枚あたり最大 16 MB、ピクセル数の制限なし。 BeatAPI がモデル向けに各画像をリサイズし、スマートフォンの写真は向きを直します。
- 2.0 のレスポンスは
"model": "beat-moderation-2.0"、"policy_version": "2026-10-15"で、画像を送信した場合のcategory_applied_input_typesは["text", "image"]です。それ以外は下記のレスポンスと同じです。
HTTP 400 で拒否される場合
一部だけが判定されることはなく、HTTP 400 で拒否されたリクエストは課金されません。
しきい値と総合判定
どのカテゴリも 0.6 に達するとしきい値超過(判定は block)です。次の例外があります。verdict は、各カテゴリのしきい値より 0.25 低い値から review となり、下限は 0.15 です。
より厳しい、または緩いしきい値が必要な場合は、category_scores に独自の値を適用してください。
料金とトークン数
入力 1M トークンあたり $0.08、出力は無料です。実測値は次のとおりです。
各レスポンスの usage.input_tokens で、その呼び出しで計上された量を確認できます。テキストも画像もログには保存されません。
クイックスタート
以下は、このリクエストに対する実際のレスポンスです。
illicit のスコアは 0.99 で、しきい値の 0.6 を超えています。そのため、categories.illicit と flagged は true、verdict は block になります。
OpenAI SDK(Python)
クライアントの接続先を BeatAPI に設定し、通常どおり moderations.create を呼び出します。BeatAPI が追加するフィールドも、型付きの結果から取得できます。
JavaScript
画像
画像は、OpenAI の API と同じく input 配列の image_url 要素として送信します。画像だけでも、関連するテキスト(プロンプトやキャプション)を同じ配列の text 要素として添えても構いません。
このリクエストの画像は一般的な商品ポスターで、単体では許可されます。このプロンプトを添えた場合の実際のレスポンスは verdict: "block"、sexual が 1、sexual_level は explicit でした。画像とテキストはあわせて判定され、テキストは単独でも評価されるため、問題のない画像が、その画像に対する不適切な依頼を隠すことはありません。
- リンクまたは埋め込み。
image_url.urlにはhttp(s)のリンク、またはdata:image/jpeg;base64,...のような base64 の data URL を指定します。リンクは BeatAPI が取得するため、公開されたアドレスである必要があります。プライベートアドレスへのリンクは拒否されます。 - PNG、JPEG、WebP、最大 4 MB、かつ 1,600 万画素まで。形式は data URL のラベルではなくファイル自体から判定します。改行を含む base64、URL セーフ形式、パディングなしの base64 も受け付けます。
- 1 回の呼び出しにつき画像 1 枚。8,000 文字までのテキストを 1 件添えられます。
- 画像を含むリクエストのレスポンスは
"model": "beat-moderation-vision-1.0"、"policy_version": "2026-10-13"となり、category_applied_input_typesは["image"]、テキストを添えた場合は["text", "image"]です。そのほかは以下の説明と同じです。 - 1 回の呼び出しは約 0.5 秒で、リンクの場合は画像の取得時間が加わります。
リクエスト
レスポンス
レスポンスは同期的に返され、成功した HTTP レスポンスに判定結果が含まれます。ポーリングは不要です。
カテゴリ
OpenAI と同じ名前の 7 カテゴリを判定し、それぞれ 0~1 のスコアを返します。テキストと画像で同じ 7 カテゴリを使用します。
OpenAI の 6 つのサブカテゴリキー(harassment/threatening、hate/threatening、illicit/violent、self-harm/intent、self-harm/instructions、violence/graphic)は、型付き SDK との互換性を保つために含まれていますが、個別には判定されません。常に false、スコアは 0、category_applied_input_types は空のリストです。これらを基に判定ルールを作らないでください。
しきい値と総合判定
判定対象の各カテゴリにはしきい値があります。categories[k] はカテゴリのスコアとしきい値の比較結果を示し、いずれかのスコアがしきい値に達すると flagged が true になります。
Beat Moderation 2.0 には独自のしきい値があり、このページ冒頭のセクションに記載しています。上の表は、名前を指定した場合の従来のモデルのものです。
sexual_level は、スコアとは独立して、コンテンツの性的な内容の程度を示します。
category_scores.sexual は explicit に該当する確率です。性的な示唆にとどまるコンテンツでは、このスコアは低く、代わりに sexual_level: "suggestive" と verdict: "review" が返ります。そのような内容も判断の対象にする場合は、この 2 つのフィールドを確認してください。画像にテキストを添えた場合は、両者のうち高いほうが返ります。
より厳しい、または緩いしきい値が必要な場合は、category_scores に独自のしきい値を適用してください。
policy_version は、スコアを算出したポリシーを識別します。異なるポリシーバージョンのスコアは比較できず、テキスト用モデルと画像用モデルのスコアも比較できないため、スコアを保存する際はバージョンも一緒に保存してください。
制限
以下の制限は、名前を指定した場合の従来のモデルのものです。Beat Moderation 2.0 はテキスト 1 件と最大 4 枚の画像を受け付け、その制限はこのページ冒頭のセクションに記載しています。
- 1 回の呼び出しにつきテキスト 1 件、画像 1 枚、またはその両方。 テキストや画像が複数ある場合は HTTP 400 で拒否され、一部だけが判定されることもありません。項目ごとにリクエストを送信してください。
- テキストは最大 8,000 文字。 超過したテキストは切り詰められず、HTTP 400 で拒否されます。分割して各部分を送信してください。長さは UTF-16 コードユニットで数えるため、多くの絵文字は 2 文字分として数えられます。
- 画像は PNG、JPEG、WebP、最大 4 MB・1,600 万画素。 それ以外は HTTP 400 で拒否され、何が問題かがメッセージに示されます。
- 音声と動画には対応していません。
- 同期処理。 ストリーミングはなく、ポーリングするタスクもありません。サーバー側の処理時間は、テキストで約 0.2 秒、画像で約 0.5 秒です。
エラー
エラーは BeatAPI 標準の形式で返され、code、message、retryable、request_id、HTTP 429 の場合は retry_after_seconds を含みます。一覧と再試行の方針はエラーを参照してください。このエンドポイントのエラーオブジェクトには、OpenAI の type と param(常に null)も含まれるため、OpenAI SDK は通常どおり対応する例外を送出します。
画像に問題がある場合、HTTP 400 の message は次のとおりです。
破損した画像や途中で切れた画像は、これらの確認を通過したあと、モデルの処理で失敗することがあります。その場合は HTTP 503 が返り、ファイルが破損している可能性がメッセージに示されます。同じファイルで再試行しても失敗します。
最初の表の例外は、公式 Python SDK が実際に送出したものです。401、402、403、429 は 2026-10-12(openai 2.48.0)、400 と 503 は 2026-10-13(openai 3.29.0)にも確認しており、503 は途中で切れた JPEG で発生させました。
呼び出しが失敗した場合、判定は行われていません。エラーを「許可」とみなさないでください。HTTP 400 で拒否されたリクエストは課金されません。
課金
コンテンツ判定は入力トークンのみを対象に課金されます。既定の beat-moderation-2.0 は入力 1M トークンあたり 0.065、画像を含むリクエストが入力 1M トークンあたり $0.23 です。3 つのモデルすべてが料金ページに掲載されています。
従来のモデルでは、判定ポリシーは毎回の呼び出しに含まれ、約 1,150 トークンが入力として計上されます。そのため、短いテキストでも最低限の入力使用量が発生します。画像は、サイズにかかわらず最大で約 1,000 トークンが加わります。
従来のモデルのトークン数です(2.0 の値はこのページ冒頭のセクションにあります)。
各レスポンスの usage.input_tokens で、実際に計上されたトークン数を確認し、呼び出しごとの費用を照合できます。
プライバシー
送信したテキストと画像はリクエストログに記録されません。保存されるのは、テキストの長さ、画像の枚数、スコア、ポリシーバージョンのみです。リンクで送信した画像は、そのリクエストのために 1 回だけ取得されます。
対応範囲と限界
- 分類器であり、結果を保証するものではありません。 明白な違反は高い信頼性で検出します。一方、隠語、同音異義語、偽装したスパム、特に中国語でのこうした表現は、検出の信頼性が低くなります。利用の前に、自分のコンテンツで検証してください。
- 画像は、境界的な内容ではテキストほど判定が安定しません。 芸術作品の裸体、格闘技、歴史的な写真はしきい値に近いスコアになり、似た画像でも
allow、review、blockに分かれることがあります。画像の中に描かれた文字(ミームや QR コード付きの広告)は、当社のテストの対象外です。 sexual/minorsは、既知の虐待コンテンツを検出するハッシュ照合の代わりにはなりません。 また、法令上求められる通報義務を代替するものでもありません。- 音声と動画は判定しません。
- 同じ入力でもスコアが完全に一致するとは限りません。 当社のテストでは、同一の呼び出し間で最大 0.04 の変動がありました。しきい値に近いコンテンツは、そのどちら側にも判定される可能性があります。しきい値付近のスコアは境界的な結果として扱ってください。
エージェント
エージェントは Capabilities API から同じ判定機能を利用できます。カタログ上の識別子は model:beat-moderation-1.0 と model:beat-moderation-vision-1.0 です。Run の入力は、テキストでは {"input": "…"}、画像では {"image_url": "…", "input": "任意のテキスト"} で、結果は上記と同じレスポンスボディです。この経路のエラーは、type と param を含まない標準形式で返されます。
Beat Moderation 2.0 は model:beat-moderation-2.0 です。Run の入力は {"input": "テキスト", "image_urls": ["https://..."]} で、画像が 1 枚だけなら image_url でも指定できます。

