すべてのプロダクト
Search
ドキュメントセンター

Alibaba Cloud Model Studio:マルチモーダル埋め込み API の詳細

最終更新日:Nov 09, 2025

マルチモーダル埋め込みモデルは、テキスト、画像、または動画をベクターに変換します。動画分類、画像分類、クロスモーダル検索などのタスクに適しています。

コア機能

  • クロスモーダル検索: テキストから画像、画像から動画、画像から画像への検索など、クロスモーダルなセマンティック検索を実行します。

  • セマンティック類似度の計算: 統一されたベクター空間で、異なるモダリティのコンテンツ間のセマンティック類似度を測定します。

  • コンテンツの分類とクラスタリング: セマンティックベクター埋め込みに基づいて、インテリジェントなグルーピング、タギング、クラスタリング分析を実行します。

主要な属性: テキスト、画像、動画などのすべてのモダリティから生成されたベクター埋め込みは、同じセマンティック空間にあります。余弦類似度を計算することで、クロスモーダルなマッチングと比較を直接実行できます。モデルの選択と使用方法の詳細については、「テキストとマルチモーダル埋め込み」をご参照ください。
重要

このモデルサービスは、中国 (北京) リージョンでのみ利用可能です。中国 (北京) リージョンの API キー を使用する必要があります。

概要

汎用マルチモーダル埋め込み API を呼び出す際には、以下の入力タイプとフォーマットの制限が適用されます。

API は、単一のテキストセグメント、単一の画像、または単一の動画ファイルをサポートします。また、テキストと画像など、異なるタイプの組み合わせも可能です。呼び出しごとに許可される組み合わせは 1 つだけで、ファイルは表にある長さとサイズの要件を満たす必要があります。

前提条件

API キーを取得し、API キーを環境変数として設定する必要があります。SDK を使用して呼び出しを行う場合は、DashScope SDK をインストールする必要もあります。

HTTP

POST https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding

リクエスト

マルチモーダル埋め込み

curl --silent --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "tongyi-embedding-vision-plus",
    "input": {
        "contents": [ 
            {"text": "Multimodal embedding model"},
            {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
            {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"},
            {"multi_images": [
                "https://img.alicdn.com/imgextra/i2/O1CN019eO00F1HDdlU4Syj5_!!6000000000724-2-tps-2476-1158.png",
                "https://img.alicdn.com/imgextra/i2/O1CN01dSYhpw1nSoamp31CD_!!6000000005089-2-tps-1765-1639.png"
                ]
              }
        ]
    }
}'

ヘッダー

Content-Type string (必須)

リクエストのコンテンツタイプ。これは `application/json` または `text/event-stream` に設定できます。`text/event-stream` の値は、Server-Sent Events (SSE) 応答を有効にします。

Content-Type string (必須)

リクエストのコンテンツタイプ。このパラメーターを application/json に設定します。

Authorization string (必須)

リクエストの身分認証情報。この API は、身分認証に Model Studio API キーを使用します。例: Bearer sk-xxxx。

リクエストボディ

model string (必須)

概要 の表にあるモデルの名前。

input object (必須)

入力コンテンツ。

プロパティ

contents array (必須)

処理するコンテンツのリスト。各要素は、コンテンツのタイプと値を指定する辞書または文字列です。フォーマットは {"modality_type": "input_string_or_image/video_url"} です。textimagevideo、および multi_images モダリティタイプがサポートされています。

  • テキスト: キーは text です。値は文字列です。辞書を使用せずに文字列を直接渡すこともできます。

  • 画像: キーは image です。値は、一般にアクセス可能な URL または Base64 エンコードされたデータ URI です。データ URI のフォーマットは data:image/{format};base64,{data} です。ここで、{format}jpegpng などの画像フォーマットで、{data} は Base64 エンコードされた文字列です。

  • 動画: キーは video です。値は、一般にアクセス可能な URL である必要があります。

parameters object (任意)

プロパティ

top_n int (任意)

ソート後に返すドキュメントの数。指定された値がドキュメントの総数より大きい場合、すべてのドキュメントが返されます。このパラメーターを指定しない場合、すべてのドキュメントが返されます。

return_documents bool (任意)

ソート結果に元のドキュメントを返すかどうかを指定します。デフォルト値は、ネットワークのオーバーヘッドを削減するために false です。

応答

成功した応答

{
    "output": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.026611328125,
                    -0.016571044921875,
                    -0.02227783203125,
                    ...
                ],
                "type": "text"
            },
            {
                "index": 1,
                "embedding": [
                    0.051544189453125,
                    0.007717132568359375,
                    0.026611328125,
                    ...
                ],
                "type": "image"
            },
            {
                "index": 2,
                "embedding": [
                    -0.0217437744140625,
                    -0.016448974609375,
                    0.040679931640625,
                    ...
                ],
                "type": "video"
            }
        ]
    },
    "usage": {
        "input_tokens": 10,
        "image_tokens": 896
    },
    "request_id": "1fff9502-a6c5-9472-9ee1-73930fdd04c5"
}

エラー応答

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

output object

タスクの出力。

プロパティ

embeddings array

埋め込み結果のリスト。各オブジェクトは入力リストの要素に対応します。

プロパティ

index int

入力リスト内の結果のインデックス。

embedding array

生成された 1024 ディメンションの埋め込み。

type string

結果に対応する入力タイプ。有効な値: text、image、video、または multi_images。

request_id string

一意のリクエスト ID。この ID を使用して問題を追跡し、トラブルシューティングできます。

code string

失敗したリクエストのエラーコード。リクエストが成功した場合、このパラメーターは返されません。詳細については、「エラーメッセージ」をご参照ください。

message string

失敗したリクエストの詳細情報。リクエストが成功した場合、このパラメーターは返されません。詳細については、「エラーメッセージ」をご参照ください。

usage object

出力に関する統計。

プロパティ

input_tokens int

リクエストの入力コンテンツ内のトークン数。

image_tokens int

入力画像または動画内のトークン数。動画入力の場合、システムは特定の数のフレームを抽出します。これはシステム構成によって決定されます。トークン数は、処理された画像または動画フレームに基づいて計算されます。

image_count int

リクエスト内の画像数。

duration int

入力動画の長さ (秒単位)。

SDK の使用

SDK 呼び出しのリクエストボディの構造は、ネイティブ HTTP 呼び出しの構造とは異なります。SDK の input パラメーターは、HTTP 呼び出しの input.contents パラメーターに対応します。

サンプルコード

画像埋め込みの生成

画像 URL の使用

import dashscope
import json
from http import HTTPStatus
# 実際には、URL をご自身の画像 URL に置き換えてください。
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
# モデル API を呼び出します。
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

ローカル画像の使用

次のサンプルコードは、ローカル画像を Base64 フォーマットに変換し、モデルを呼び出して埋め込みを生成する方法を示しています。

import dashscope
import base64
import json
from http import HTTPStatus
# 画像を読み取り、Base64 に変換します。実際には、xxx.png をご自身の画像ファイル名またはパスに置き換えてください。
image_path = "xxx.png"
with open(image_path, "rb") as image_file:
    # ファイルを読み取り、Base64 に変換します。
    base64_image = base64.b64encode(image_file.read()).decode('utf-8')
# 画像フォーマットを設定します。
image_format = "png"  # jpg や bmp など、実際のフォーマットに基づいてこれを変更してください。
image_data = f"data:image/{image_format};base64,{base64_image}"
# 入力データ。
input = [{'image': image_data}]

# モデル API を呼び出します。
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)
if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

動画埋め込みの生成

マルチモーダル埋め込みモデルは、入力として動画ファイルの URL のみをサポートします。ローカルの動画ファイルはサポートされていません。
import dashscope
import json
from http import HTTPStatus
# 実際には、URL をご自身の動画 URL に置き換えてください。
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
input = [{'video': video}]
# モデル API を呼び出します。
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

テキスト埋め込みの生成

import dashscope
import json
from http import HTTPStatus

text = "General multimodal embedding model example"
input = [{'text': text}]
# モデル API を呼び出します。
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

応答のサンプル

{
    "status_code": 200,
    "request_id": "b5623e99-ea0c-9509-9b25-20bcc99d03e9",
    "code": "",
    "message": "",
    "output": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.020782470703125,
                    -0.01399993896484375,
                    -0.0229949951171875,
                    ...
                ],
                "type": "text"
            }
        ]
    },
    "usage": {
        "input_tokens": 12,
        "image_tokens": 0
    }
}

エラーコード

呼び出しが失敗した場合は、トラブルシューティングについて「エラーメッセージ」をご参照ください。