如何使用Multimodal-Embedding API - Alibaba Cloud Model Studio

多模態向量模型將文本、映像或視頻轉換成統一的1024維浮點數向量，適用於視頻分類、映像分類、圖文檢索等。

核心能力

跨模態檢索：實現以文搜圖、以圖搜視頻、以圖搜圖等跨模態的語義搜尋。
語義相似性計算：在統一的向量空間中，衡量不同模態內容之間的語義相似性。
內容分類與聚類：基於內容的語義向量進行智能分組、打標和群集。

關鍵特性：所有模態（文本、圖片、視頻）產生的向量都位於同一語義空間，可直接通過計算餘弦相似性等方法進行跨模態匹配與比較。關於模型選型和應用方法的更多介紹，參考文本與多模態向量化。

重要

此模型服務僅在“華北2（北京）”地區提供，調用時必須使用該地區的API Key。

模型介紹、選型建議和使用方法，請參考文本與多模態向量化。

模型概覽

模型名稱

向量維度

文本長度限制

圖片/視頻大小限制

單價（每千輸入Token）

multimodal-embedding-v1

僅“華北2（北京）”地區支援

1,024

512 Token

圖片大小: ≤3MB, 數量1張
視頻: ≤10MB

免費試用，無Token額度限制。

通用多模態向量API使用過程中存在以下輸入類型與格式限制

輸入類型	語種/格式限制
文本	中/英文
圖片	JPG、PNG、BMP，支援以Base64格式或URL形式輸入。
多圖片	JPG、PNG、BMP，支援以Base64格式或URL形式輸入。
視頻	MP4、MPEG、MPG、WEBM、AVI、FLV、MKV、MOV

介面支援單段文字、單張圖片或單個視頻檔案，允許不同類型單檔案組合（如文字+圖片）。每次調用僅限一種組合形式，且檔案需符合表中長度/大小要求。

前提條件

您需要已準備工作：擷取與配置 API Key並配置API Key到環境變數（準備下線，併入配置 API Key）。如果通過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": "多模態向量模型"}, {"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" ] } ] } }'
要求標頭（Headers）
Content-Type `string` （必選）請求內容類型。可設定為application/json 或者text/event-stream（開啟 SSE 響應）。 Content-Type `string` （必選）請求內容類型。此參數必須設定為`application/json`。
Authorization `string`（必選）請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值：Bearer sk-xxxx。
請求體（Request Body）
model `string`（必選）模型名稱。設定為模型概覽中的模型名稱。
input `object` （必選）輸入內容。屬性 contents `array`（必選）待處理的內容列表。每個元素是一個字典或者字串，用於指定內容的類型和值。格式為{"模態類型": "輸入字串或映像、視頻url"}。支援`text`, `image`, `video`和`multi_images`四種模態類型。文本：key為`text`。value為字串形式。也可不通過dict直接傳入字串。圖片：key為`image`。value可以是公開可訪問的URL，或Base64編碼的Data URI。Base64格式為 `data:image/{format};base64,{data}`，其中 `{format}` 是圖片格式（如 `jpeg`, `png`），`{data}` 是Base64編碼字串。多圖片：僅`tongyi-embedding-vision-plus`與`tongyi-embedding-vision-flash`模型支援此類型。key為`multi_images`，value是多圖序列列表，每條為一個圖片，格式要求如上方所示，圖片數量最多為8張。視頻：key為`video`，value必須是公開可訪問的URL。
parameters object （可選）屬性 top_n `int`（可選）返回排序後的top_n個文檔。如果指定的值大於文檔總數，將返回全部文檔。未指定時預設返回全部文檔。 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` 請求唯一標識。可用於請求明細溯源和問題排查。
code `string` 請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。
message `string` 請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。
usage `object` 輸出資訊統計。屬性 input_tokens `int` 本次請求輸入內容的 Token 數目。 image_tokens `int` 本次請求輸入的圖片或視頻的Token數量。系統會對輸入視頻進行抽幀處理，幀數上限受系統配置控制，隨後基於處理結果計算 Token。 image_count `int` 本次請求輸入的圖片數量。 duration `int` 本次請求輸入的視頻時間長度（秒）。

SDK使用

目前的版本的 SDK 調用與原生 HTTP 調用的請求體結構不一致。SDK 的input參數對應了HTTP中的input.contents。

程式碼範例

產生圖片Embedding樣本

使用圖片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}]
# 調用模型介面
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格式後調用multimodal-embedding-v1模型進行向量化處理。

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}]

# 調用模型介面
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))

產生視頻Embedding樣本

多模態向量化模型目前僅支援以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}]
# 調用模型介面
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))

產生文本Embedding樣本

import dashscope
import json
from http import HTTPStatus

text = "通用多模態表徵模型樣本"
input = [{'text': text}]
# 調用模型介面
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))

輸出樣本

JSON

{
    "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
    }
}

錯誤碼

如果模型調用失敗並返回報錯資訊，請參見錯誤資訊進行解決。