AI Search Open Platform 画像コンテンツ抽出 - OpenSearch - Alibaba Cloud ドキュメントセンター

OpenSearch では、API 経由で画像内容抽出サービスを呼び出し、ビジネスワークフローに統合することで、解析されたテキストを画像検索や質問応答に利用できます。

サービス一覧

サービス名	サービス ID	説明	API QPS 制限
Image Content Understanding Service 001	ops-image-analyze-vlm-001	マルチモーダル大規模モデルを使用して画像コンテンツを分析し、テキストを認識します。これにより、画像リトリーバルや質疑応答などのアプリケーションを可能にします。	10 説明より高い API QPS 制限をリクエストするには、テクニカルサポートにチケットを送信してください。
Image OCR Service 001	ops-image-analyze-ocr-001	OCR を使用して画像からテキストを抽出することで、画像リトリーバルや質疑応答などのアプリケーションを可能にします。	10 説明より高い API QPS 制限をリクエストするには、テクニカルサポートにチケットを送信してください。

認証情報の取得

AI Search オープンプラットフォームでは、認証に API キーが必要です。手順については、「API キーの取得」をご参照ください。
サービスエンドポイントの取得

パブリックネットワークまたは VPC 経由でサービスを呼び出せます。詳細については、「サービスエンドポイントの取得」をご参照ください。

非同期抽出タスクの作成

リクエストメソッド

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/image-analyze/{service_id}/async

host ：API サービスのエンドポイントです。パブリックネットワーク経由、または VPC 経由で API サービスにアクセスできます。詳細については、「エンドポイントの取得」をご参照ください。

AI Search Open Platform コンソールで、左側メニューから [API キー] を選択します。次に、ページ上部の [アクセスドメイン名] セクションで、[パブリック API ドメイン名] と [プライベート API ドメイン名] を確認できます。

workspace_name ：ワークスペース名。例： default。
service_id ：組み込みシステムサービス ID。例： ops-image-analyze-vlm-001。

リクエストパラメータ

ヘッダーパラメータ

API キー認証

パラメーター	タイプ	必須	説明	例
`Content-Type`	文字列	必須	リクエストボディのメディアタイプを指定します。`application/json` である必要があります。	`application/json`
`Authorization`	文字列	必須	`Bearer` を先頭に付けた、認証用の API キーです。	`Bearer OS-d1**2a`

ボディパラメーター

パラメーター	型	必須	説明	例
service_id	文字列	必須	組み込みサービス ID： ops-image-analyze-vlm-001 ops-image-analyze-ocr-001	ops-image-analyze-vlm-001
document.url	文字列	任意	ファイルの URL です。このパラメーターまたは `document.content` のいずれかを指定する必要があります。`http` および `https` プロトコルをサポートしています。	http://path/to/*.jpg
document.content	文字列	任意	ファイルの Base64 エンコードされたコンテンツです。このパラメーターまたは `document.url` のいずれかを指定する必要があります。	"aGVsbG8gd29ybGQ="
document.file_name	文字列	任意	ファイル名です。このパラメーターを省略した場合、`document.url` から名前を推測します。`document.url` も省略された場合は必須です。	test.jpg
document.file_type	文字列	任意	ファイルタイプです (例： `jpg`、`jpeg`、`png`、`bmp`、`tiff` )。このパラメーターを省略した場合、`document.file_name` の拡張子からタイプを推測します。タイプが自動的に推測できない場合は必須です。	jpg

戻り値

パラメータ	タイプ	説明	値
result.task_id	文字列	非同期画像分析タスクの ID。	6177bf71-f87f-4d86-ab0c-e2b64dfe****

cURL リクエスト

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/image-analyze/ops-image-analyze-vlm-001/async"
  --data '{
    "document": {
      "url": "https://img01.yzcdn.cn/****/2017/05/11/FoTMgBa0SvUaAeFruY7i7O_EUMhf.jpg%21middle.jpg",
      "file_type": "jpg"
    }
  }' \

レスポンス例

正常応答

{
	"request_id":"CD4E26F0-23FF-449C-83DC-20CC8FF1****",
        "latency":8.0,
        "http_code":200,
        "result":{
                  "task_id":"cd4e26f0-23ff-449c-83dc-20cc8ff1****"
        }
}

エラーレスポンスの例

アクセスリクエストが失敗した場合、出力にはエラーを示す code と message が含まれます。

{
      "request_id":"0CCAC03B-D83F-432F-B6BA-C3049576****",
      "latency":0.0,
      "code":"InvalidParameter",
      "http_code":400,
      "message":"document.content または document.url が必要ですが、両方を同時に指定することはできません"
}

非同期抽出タスクのステータス

リクエストメソッド

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/image-analyze/{service_id}/async/task-status?task_id=${task_id}

host：API サービスエンドポイントです。API サービスは、パブリックネットワークまたは VPC 経由で呼び出すことができます。詳細は、サービスエンドポイントの取得をご参照ください。
workspace_name：ワークスペース名です。例： default
service_id：組み込みのサービス ID です。例： ops-image-analyze-vlm-001
task_id：画像分析タスクの作成時に、レスポンスで返されるタスク ID です。例： cd4e26f0-23ff-449c-83dc-20cc8ff1****

リクエストパラメーター

ヘッダーパラメーター

API キー認証

パラメーター	タイプ	必須	説明	例
Content-Type	文字列	○	リクエストタイプです。`application/json` である必要があります。	application/json
Authorization	文字列	○	認証用の API キーです。`Bearer` をプレフィックスとして付与します。	Bearer OS-d1**2a

レスポンスパラメーター

パラメーター	型	説明	例
request_id	文字列	API 呼び出しの一意の識別子です。	3C09570D-12DB-46B4-BF0F-A100D79B****
latency	浮動小数点数/整数	リクエストのレイテンシー (ミリ秒) です。	3.0
result.task_id	文字列	非同期タスクの ID です。このパラメーターは、同期呼び出しでは返されません。	a7e4c0f6-874c-47e3-b05b-02278a96e****
result.status	文字列	タスクステータスです。有効な値は次のとおりです： `PENDING` ：タスクは保留中です。 `SUCCESS` ：タスクは成功です。 `FAILED` ：タスクは失敗です。	SUCCESS
result.data	オブジェクト	画像分析の結果です。	{"content":"The image shows XXXX", "content_type":"plain"}
result.data.content	文字列	抽出された画像コンテンツです。	"XXX"
result.data.content_type	文字列	出力のコンテンツタイプです。値は常に `plain` です。	plain
usage.token_count	整数	出力のトークン数です。このパラメーターは `ops-image-analyze-vlm-001` サービスが対象です。	1234
usage.pv_count	整数	1 に固定された呼び出し数です。このパラメーターは `ops-image-analyze-ocr-001` サービスが対象です。	1

cURL リクエストの例

curl -X GET \
-H"Content-Type: application/json" \
-H "Authorization: Bearer お使いのAPIキー" \
"http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/image-analyze/ops-image-analyze-vlm-001/async/task-status?task_id=d9781786-20b8-4fb4-bbb5-38f82e69****"

レスポンス例

成功レスポンス

{
      "request_id":"3C09570D-12DB-46B4-BF0F-A100D79B****",
      "latency":3.0,
      "http_code":200,
      "result":{
           "status":"SUCCESS",
           "data":{
                "content":"画像には、果物や野菜に囲まれたWMF社のミキサーが写っています。その隣には、ストローが差さった赤いジュースのグラスがあります。テーブルの上には、レモンスライス、イチゴ、キウイフルーツがあります。隅には、切ったパイナップルとオレンジがあります。ミキサーの中には、ジュース用に刻んだニンジンが入っています。健康的で食欲をそそる光景です。",
                "content_type":"plain"
            },
            "task_id":"d9781786-20b8-4fb4-bbb5-38f82e69****"
       },
            "usage":{
                "token_count":95
            }
}

エラーレスポンスのサンプル

アクセスリクエストが失敗した場合、出力にはエラーを示す code と message が含まれます。

{
  "request_id":"153FC253-468D-4C46-873E-2AEB918C****",
  "latency":2.0,
  "code":"BadRequest.TaskNotExist",
  "http_code":404,
  "message":"タスク[d9781786-20b8-4fb4-bbb5-38f82e690b****] は存在しません"
}

同期抽出タスクの作成

リクエストメソッド

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/image-analyze/{service_id}/sync

パラメータ

host：API サービスエンドポイントです。API サービスは、パブリックネットワークまたは VPC 経由で呼び出すことができます。詳細については、「サービスエンドポイントの取得」をご参照ください。
workspace_name：お使いのワークスペース名です。例：default
service_id：組み込みサービス ID です。例：ops-image-analyze-vlm-001

パラメータ

ヘッダーパラメーター

API キー認証

パラメーター	タイプ	必須	説明	サンプル値
Content-Type	文字列	はい	リクエストのメディアタイプ	application/json
Authorization	文字列	はい	API キー	Bearer OS-d1**2a

ボディパラメータ

パラメーター	型	必須	説明	例
service_id	文字列	必須	組み込みサービスの ID です。有効な値： ops-image-analyze-vlm-001 ops-image-analyze-ocr-001	ops-image-analyze-vlm-001
document.url	文字列	任意	ファイルの URL です。HTTP と HTTPS をサポートしています。 `document.url` または `document.content` のいずれかを指定する必要があります。	http://path/to/***.jpg
document.content	文字列	任意	Base64 でエンコードされたファイルのコンテンツです。 `document.url` または `document.content` のいずれかを指定する必要があります。	"aGVsbG8gd29ybGQ="
document.file_name	文字列	任意	ファイル名です。このパラメーターを省略した場合、 `document.url` から名前を推測します。 `document.url` を指定しない場合、このパラメーターは必須です。	test.jpg
document.file_type	文字列	任意	ファイルタイプです。このパラメーターを省略した場合、ファイル名拡張子からタイプを推測します。タイプが推測できない場合は、ファイルタイプを明示的に指定する必要があります。例： `jpg`、 `jpeg`、 `png`、 `bmp`、 `tiff`。	jpg

レスポンスパラメーター

パラメーター	タイプ	説明	値の例
result.status	文字列	タスクステータスです。値は次のとおりです： PENDING：進行中 SUCCESS：成功 FAIL：失敗	SUCCESS
result.error	文字列	`result.status` が `FAIL` の場合のエラーメッセージです。それ以外の場合は空です。	Failed to decrypt the document.
result.data	オブジェクト	画像分析の結果です。	{"content":"The image shows XXXX", "content_type":"plain"}
result.data.content	文字列	画像から抽出されたコンテンツです。	"XXX"
result.data.content_type	文字列	出力コンテンツのタイプです。値は常に `plain` です。	plain
request_id	文字列	API 呼び出しの一意の識別子です。	B4AB89C8-B135-xxxx-A6F8-2BAB801A2CE4
latency	数値	リクエストのレイテンシー (ms) です。	10
usage	オブジェクト	この API 呼び出しの使用量です。	"usage": { "token_count": 1234 }
usage.token_count	整数	`ops-image-analyze-vlm-001` サービスでカウントされる出力トークン数です。	1234
usage.pv_count	整数	`ops-image-analyze-ocr-001` サービスでカウントされる呼び出し数です。値は 1 に固定されています。	1

cURL

このセクションでは、API 呼び出しのサンプルと、関連する技術用語の用語集を紹介します。
API 呼び出しの例

次の例では、画像分析 API エンドポイントに対して同期呼び出しを実行する方法を示します。
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
 "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/image-analyze/ops-image-analyze-vlm-001/sync" \
-d "{
      \"document\":{
            \"url\":\"https://img01.yzcdn.cn/****/2017/05/11/FoTMgBa0SvUaAeFruY7i7O_EUMhf.jpg%21middle.jpg\",
            \"file_type\":\"jpg\"
      }
}"
用語集

次の表では、この API 呼び出しで使用される技術用語、標準表記、関連する規約を示します。



用語
標準表記
タイプ
注記




API キー
API key
業界標準
業界標準の用語です。本文では小文字を使用します。


China (Hangzhou)
China (Hangzhou)
Alibaba Cloud リージョン
公式リージョン名です。URL 内の識別子 hangzhou はシステムで使用されます。


Open Search
Open Search
Alibaba Cloud 製品
公式製品名です。URL 内の識別子 opensearch はシステムで使用されます。


ワークスペース
workspace
業界標準
一般的なクラウドリソースの概念です。小文字を使用します。


画像分析
image analysis
業界標準
機能を表す名称です。URL 内の識別子 image-analyze はシステムで使用されます。


同期 / 非同期
sync / async
業界標準
同期操作および非同期操作の標準用語です。


ドキュメント
document
JSON フィールド
標準の JSON フィールド名です。小文字を使用します。


URL
url
JSON フィールド
標準の JSON フィールド名です。小文字を使用します。


ファイルタイプ
file_type
JSON フィールド
標準の JSON フィールド名です。小文字を使用します。



UI 要素

この API 呼び出しの例は、ユーザーインターフェース (UI) 要素を参照しません。

レスポンス例

成功レスポンス

{
    "request_id":"BB5CD4C3-C8B6-40E7-A037-4ADAE88A****", 
    "latency":12525.0,
    "http_code":200,
    "result":{
        "status":"SUCCESS",
        "data":{
              "content":"画像には、果物や野菜に囲まれた WMF 社のミキサーが写っています。ミキサーの隣には、ストローが差さった赤いジュースの入ったカップがあります。テーブルの上には、数枚のレモンスライス、いくつかのイチゴ、そしてキウイフルーツが散らばっています。テーブルの隅には、切り取りパイナップルとオレンジがあります。さらに、ミキサーの中には刻んだニンジンが入っており、ジュースにする準備ができています。すべてが体に良さそうで美味しそうです。",
              "content_type":"plain"
        }
      },
      "usage":{
          "token_count":95
      }
}

エラーレスポンス

失敗したアクセスリクエストは、エラーを示す code と message を返します。

{
    "request_id": "6F33AFB6-A35C-4DA7-AFD2-9EA16CCF****",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\"
}

ステータスコード

HTTP ステータスコード	エラーコード	説明
200	-	リクエストが成功しても、タスクの成功を保証するものではありません。`result.status` でタスクステータスを確認してください。
404	BadRequest.TaskNotExist	タスクが存在しません。
400	InvalidParameter	リクエストが無効です。
500	InternalServerError	内部エラーが発生しました。

ステータスコードの詳細は、「ステータスコード」をご参照ください。

サービス一覧

非同期抽出タスクの作成

リクエストメソッド

URL

リクエストパラメータ

ヘッダー パラメータ

ボディ パラメーター

戻り値

cURL リクエスト

レスポンス例

正常応答

エラーレスポンスの例

非同期抽出タスクのステータス

リクエストメソッド

URL

リクエストパラメーター

ヘッダー パラメーター

レスポンスパラメーター

cURL リクエストの例

レスポンス例

成功レスポンス

エラーレスポンスのサンプル

同期抽出タスクの作成

リクエストメソッド

URL

パラメータ

パラメータ

ヘッダー パラメーター

ボディパラメータ

レスポンスパラメーター

cURL

レスポンス例

成功レスポンス

エラーレスポンス

ステータスコード

ヘッダーパラメータ

ボディパラメーター

ヘッダーパラメーター

ヘッダーパラメーター