画像 OCR の同期タスク送信 - Content Moderation

このトピックでは、同期画像検出 API を呼び出して一般的な光学文字認識 (OCR) を実行する方法について説明します。一般的な OCR は、画像内のテキスト内容を検出し、その結果を返します。

注意事項

/green/image/scan API オペレーションを使用して同期画像検出を実行します。

このオペレーションを呼び出して、同期画像検出タスクを作成できます。HTTP リクエストの構築方法については、「リクエスト構造」をご参照ください。また、あらかじめ作成された HTTP リクエストを使用することもできます。詳細については、「SDK 概要」をご参照ください。

課金情報：

このオペレーションの呼び出しに対して課金されます。課金方法の詳細については、をご参照ください。
検出タイムアウト：

同期モデレーションリクエストで許容される最大応答時間は 6 秒です。6 秒以内にモデレーションが完了しない場合、タイムアウトエラーが返されます。リアルタイムでのモデレーション結果を必要としない場合は、非同期モデレーションリクエストを送信できます。ほとんどの場合、同期モデレーションオペレーションは呼び出しやすいため、同期モデレーションリクエストの送信を推奨します。同期モデレーションオペレーションの呼び出しでは、タイムアウト期間を 6 秒に設定することを推奨します。
戻り値：

通常、同期モデレーションリクエストを送信後、1 秒以内にモデレーション結果が返されます。ただし、システム内で大量のリクエストを処理する必要がある場合、画像サイズが大きい場合、または画像に多数の単語が含まれる場合など、特殊なシナリオでは応答時間が延長されることがあります。OCR の処理速度は、画像内の単語数に反比例します。モデレーション対象の画像に多数の単語が含まれる場合は、非同期モデレーションリクエストの送信を推奨します。
画像要件：
- 画像の URL は HTTP または HTTPS の URL である必要があります。
- 画像は PNG、JPG、JPEG、BMP、GIF、WEBP 形式である必要があります。
- 1 枚の画像のサイズは最大 20 MB です。この画像サイズ制限は、同期および非同期の両方のモデレーションオペレーションに適用されます。
- 画像のダウンロード時間は 3 秒に制限されています。3 秒以内に画像のダウンロードに失敗した場合、タイムアウトエラーが返されます。
- モデレーション効果を確保するため、少なくとも 256 × 256 ピクセルの画像を提出することを推奨します。
- 画像のモデレーションを行うオペレーションの応答時間は、これらの画像のダウンロード時間によって異なります。モデレーション対象の画像を格納する際には、安定性と信頼性の高いストレージサービスをご利用ください。Object Storage Service (OSS) またはコンテンツデリバリーネットワーク (CDN) のご利用を推奨します。

QPS 制限

アカウントあたり、このオペレーションを 1 秒間に最大 10 回呼び出すことができます。1 秒あたりの呼び出し回数がこの制限を超えると、速度制限が発生し、業務に影響を及ぼす可能性があります。このオペレーションを呼び出す際には、この制限を十分にご確認ください。

リクエストパラメーター

名前	型	必須	例	説明
bizType	String	いいえ	default	ビジネスシナリオです。このシナリオは、 Content Moderation コンソールで作成できます。詳細については、「機械審査を支援するポリシーのカスタマイズ」をご参照ください。
scenes	StringArray	はい	["ocr"]	検出シナリオです。ocr を指定します。
tasks	JSONArray	はい		検出対象です。JSON 配列の各要素は、1 つの検出タスクを表す構造体です。最大 100 個の要素（つまり、一度に最大 100 個のコンテンツ項目）を提出できます。100 個の要素を提出するには、同時タスク数を 100 以上に増加させる必要があります。各要素の構造については、「task」をご参照ください。

表 1. task
名前	型	必須	例の値	説明
dataId	String	いいえ	test_data_xxxx	データ ID です。リクエスト内のすべての ID が一意であることを確認してください。
url	String	はい	https://aliyundoc.com/test_image_xxxx.png	インターネット経由でアクセス可能な HTTP または HTTPS の URL です。URL の長さは最大 2,048 文字です。
interval	Integer	いいえ	2	連続してキャプチャされる 2 つのフレーム間の間隔です。このパラメーターは GIF または長尺画像のモデレーション専用です。 GIF 画像はフレームの配列と見なすことができます。この interval パラメーターで指定された n フレームごとに 1 つのフレームがモデレーションのためにキャプチャされます。このパラメーターが指定されている場合にのみ、システムは GIF 画像からフレームをキャプチャします。長尺画像は縦モードまたは横モードになります。縦長の画像をモデレーションする場合、フレームの総数を以下のように計算できます：高さを幅で割り、結果を最も近い整数に四捨五入します。縦長の画像では、高さが 400 ピクセルより大きく、高さと幅の比率が 2.5:1 より大きくなります。横長の画像をモデレーションする場合、フレームの総数を以下のように計算できます：幅を高さで割り、結果を最も近い整数に四捨五入します。横長の画像では、幅が 400 ピクセルより大きく、幅と高さの比率が 2.5:1 より大きくなります。デフォルトでは、GIF 画像または長尺画像の最初のフレームのみがモデレーションされます。interval パラメーターを使用して、システムが連続してキャプチャする 2 つのフレーム間の間隔を指定できます。これにより、モデレーションコストを削減できます。説明 interval パラメーターと maxFrames パラメーターはペアで使用する必要があります。たとえば、GIF 画像または長尺画像のモデレーションにおいて、interval パラメーターを 2 に設定し、maxFrames パラメーターを 100 に設定した場合、2 フレームごとに 1 フレームがモデレーションされ、最大 100 フレームがモデレーションされます。料金は、実際にモデレーションされたフレーム数に基づいて計算されます。
maxFrames	Integer	いいえ	100	キャプチャするフレームの最大数です。このパラメーターは GIF または長尺画像のモデレーション専用です。デフォルト値：1。この interval パラメーターの値と `maxFrames` パラメーターの値の積が、GIF 画像または長尺画像のフレーム総数より小さい場合、フレームのキャプチャ間隔は、画像のフレーム総数を maxFrames パラメーターの値で割った結果を切り上げた整数に自動的に変更されます。これにより、全体的なモデレーション効果が向上します。

返されたデータ

名前	型	例	説明
code	Integer	200	エラーコードです。HTTP ステータスコードと同じです。
msg	String	OK	リクエストに対する応答メッセージです。
dataId	String	test_data_xxxx	モデレーション対象の ID です。説明モデレーションリクエストで dataId パラメーターを設定した場合、この dataId リクエストパラメーターの値がここに返されます。
taskId	String	img5A@k7a@B4q@6K@d9nfKgOs-1s****	検出タスクの ID です。
url	String	https://aliyundoc.com/test_image_xxxx.png	インターネット経由でアクセス可能な HTTP または HTTPS の URL です。URL の長さは最大 2,048 文字です。
results	Array		返された結果です。呼び出しが成功した場合（code=200）、結果には 1 つ以上の要素が含まれます。各要素は構造体です。構造の詳細については、「result」をご参照ください。

表 2. result
名前	型	例	説明
scene	String	ocr	検出シナリオです。値は ocr です。
label	String	ocr	検出結果の分類です。有効な値は以下のとおりです。 normal：画像内にテキストが検出されません。 ocr：画像にテキストが含まれています。
suggestion	String	review	推奨される後続操作です。有効な値は以下のとおりです。 pass：戻り値を無視できます。 review：検出されたテキストのレビューが必要です。
rate	Float	99.91	OCR シナリオでは、この戻り値を無視できます。
ocrLocations	Array		静的画像（GIF 以外）にテキストが含まれている場合、このパラメーターは検出された各テキスト項目に関する情報を返します。構造の詳細については、「ocrLocation」をご参照ください。説明テキストが検出されない場合、このパラメーターは返されません。
ocrData	Array	["hello, this is a test text."]	静的画像（GIF 以外）にテキストが含まれている場合、このパラメーターは検出されたすべてのテキストを結合したものを返します。結合されたテキストは通常、配列の最初の要素に格納されます。説明テキストが検出されない場合、このパラメーターは返されません。
frames	Array	xxx	アニメーション画像（GIF）にテキストが含まれている場合、このパラメーターはキャプチャされた各フレームとその対応するテキストを返します。説明複数のフレームがキャプチャされた場合にのみ、この結果が返されます。

表 1. ocrLocation
パラメーター	型	例	説明
text	String	hello	モデレーション対象の画像内で検出された単一のテキスト項目です。
x	Float	41	テキスト領域の左上隅と y 軸との距離です。座標原点は画像の左上隅です。単位：ピクセル。
y	Float	84	テキスト領域の左上隅と x 軸との距離です。座標原点は画像の左上隅です。単位：ピクセル。
w	Float	83	テキスト領域の幅です。単位：ピクセル。
h	Float	26	テキスト領域の高さです。単位：ピクセル。

例

リクエストのサンプル

http(s)://[Endpoint]/green/image/scan
&<共通リクエストパラメーター>
{
    "scenes": [
        "ocr"
    ],
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

応答のサンプル

{
    "code": 200,
    "data": [
        {
            "code": 200,
            "dataId": "test_data_xxxx",
            "extras": {

            },
            "msg": "OK",
            "results": [
                {
                    "label": "ocr",
                    "ocrData": [
                        "hello, this is a test text."
                    ],
                    "ocrLocations": [
                        {
                            "h": 26,
                            "text": "hello",
                            "w": 83,
                            "x": 41,
                            "y": 84
                        },
                        {
                            "h": 25,
                            "text": " this is a test text.",
                            "w": 95,
                            "x": 78,
                            "y": 114
                        }
                    ],
                    "rate": 99.91,
                    "scene": "ocr",
                    "suggestion": "review"
                }
            ],
            "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url": "https://aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "msg": "OK",
    "requestId": "C4AB08A9-AD75-4410-859B-0B9EF6DFC3C4"
}