embedding - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

Embedding models convert data, such as text, images, and videos, into vectors within a mathematical space. By calculating the distance or angle between these vectors, you can quantify data similarity. This capability is applicable to tasks such as exact search, recommendation systems, automatic classification, and anomaly detection.

Scenarios

Recommendation: Recommend relevant items based on input data. For example, you can recommend related products based on a user's purchase history and browsing records.
Clustering: Classify input data based on relevance. For example, you can categorize large volumes of news articles into topics such as technology, sports, and entertainment.
Search: Rank search results based on their relevance to the input data. For example, a text embedding model can return relevant web pages based on user search queries, and a multimodal embedding model can enable image search using text.
Anomaly detection: For example, in the finance domain, you can extract feature vectors from transaction records and mark transactions that significantly deviate from normal patterns as potential fraudulent activities.

Supported models

General text embedding

Vector dimension is the number of elements in a vector. For example, a 1,024-dimensional vector contains 1,024 numerical values. A higher dimension allows the vector to represent richer information, capturing the characteristics of the text in greater detail.

Model

Vector dimensions

Maximum rows

Maximum tokens per row

Supported languages

Unit price (Million input tokens)

Free quota (Note)

text-embedding-v4

Qwen3-Embedding series

Only available in the China (Beijing) region

2,048, 1,536, 1,024 (default), 768, 512, 256, 128, 64

8,192

Over 100 major languages, including Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian

$0.072

1 million tokens

Validity: 180 days after Model Studio is activated

text-embedding-v3

Only available in the Singapore region

1,024 (default), 768, 512, 256, 128, or 64

Over 50 major languages, including Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian

$0.07

500,000 tokens

Validity: 180 days after Model Studio is activated

Model upgrade overview

text-embedding-v3
- Language expansion: Adds support for languages such as Italian, Polish, Vietnamese, and Thai, increasing the total number of supported languages to over 50.
- Input length extension: The maximum input length is extended from 2,048 to 8,192 tokens.
- Customizable vector dimension: Allows users to choose from 1024, 768, 512, 256, 128, or 64 dimensions. The default dimension is 1024.
- No longer distinguishes between Query and Document types: Simplifies input because the `text_type` parameter no longer requires you to specify the text type.
- Sparse vector support: Allows you to specify the output of dense and sparse vectors in the API.
- Performance improvement: The pre-trained model and SFT strategy are further optimized to improve overall performance. Public data evaluation results show improved performance.
text-embedding-v4
- Language expansion: Increases the number of supported major natural languages to over 100.
- Code semantics support: The model can convert code snippets from various programming languages into vector representations. Supported languages include Python, Java, JavaScript, C++, C#, Ruby, Go, PHP, Swift, and HTML.
- Flexible vector dimension extension: Adds 2,048 and 1,536 as vector dimension options, expanding the total number of dimension options to eight.
- Performance improvement: Further model optimization has significantly improved performance in text retrieval, clustering, and classification.
- Custom instruction: You can add custom instructions to the input for different scenarios to provide task descriptions. This can improve performance by approximately 1% to 5%.

v3 and v4 model performance data

Model	MTEB	MTEB (Retrieval task)	CMTEB	CMTEB (Retrieval task)
text-embedding-v3 (512 dimensions)	62.11	54.30	66.81	71.88
text-embedding-v3 (768 dimensions)	62.43	54.74	67.90	72.29
text-embedding-v3 (1024 dimensions)	63.39	55.41	68.92	73.23
text-embedding-v4 (512 dimensions)	64.73	56.34	68.79	73.33
text-embedding-v4 (1024 dimensions)	68.36	59.30	70.14	73.98
text-embedding-v4 (2048 dimensions)	71.58	61.97	71.99	75.01

MTEB (Massive Text Embedding Benchmark) and CMTEB (Chinese Massive Text Embedding Benchmark) use a 0–100 scoring system to evaluate model performance. A higher score indicates better performance. The total score reflects the model's versatility by combining tasks such as classification, clustering, and retrieval. The Retrieval task score measures the precision of retrieval tasks, such as document search, where a higher score indicates stronger retrieval performance.

Multimodal embedding

The model generates vectors based on user input, which can be text, images, or videos. This model is suitable for tasks such as video classification, image classification, and image-text retrieval. Only available in the China (Beijing) region

Model

Data type

Vector dimension

Unit price

Free quota (Note)

Rate limit

multimodal-embedding-v1

Only available in the China (Beijing) region

float(32)

1,024

Free trial

No limit on weighted entries

RPM: 120

Model selection suggestions

Preferred models

For multimodal vector analysis involving images and videos, use multimodal-embedding-v1.

For vector analysis of plain text or code snippets, we recommend text-embedding-v4. Its performance is aligned with the open-source Qwen3-Embedding model, and its inference performance has been optimized. This model is suitable for most scenarios:

More language support: Covers over 100 major languages.
Code embedding: Adds the capability to vectorize code snippets as input. This lets you build vector index services for code snippets in frameworks such as LlamaIndex.
Flexible vector dimension selection: Provides eight dimension options: 2048, 1536, 1024, 768, 512, 256, 128, and 64. A higher dimension provides greater semantic expression accuracy, but also increases the computational and storage costs for downstream tasks.
Custom instruction: You can add task descriptions to the input content. For example, in a text retrieval scenario, you can add the `instruct` parameter to the request: "Given a web search query, retrieve relevant passages that answer the query". We recommend that you customize prompts for specific tasks and write them in English if possible. In practical applications, this method can improve performance by 1% to 5%.
Diverse output options: Supports dense and sparse vectors. Compared to the open-source Qwen3-Embedding version, this model also supports sparse vectors for different application scenarios:
- Dense vectors: More effectively captures the semantic features of text. Suitable for conventional retrieval and semantic matching scenarios.
- Sparse vectors: Reduces computational complexity and storage costs. Suitable for scenarios with limited storage resources or those that require efficient semantic matching.

For string input, the model treats the entire string as a single line and has an input length limit of 8,192 tokens. If your string content exceeds this limit, you can use the following methods to adjust the input format:

String list input: Split the input content into multiple parts to generate a string list. The following conditions must be met:
- The number of elements in the list does not exceed 10.
- The length of each element must be within 8,192 tokens.
Plain text file upload: Consolidate the input string content into a plain text file and upload it. The following conditions must be met:
- The total number of lines in the file does not exceed 10.
- The length of each line is within 8,192 tokens.

Get started

You must have obtained an API key and set the API key as an environment variable. If you use the OpenAI SDK or DashScope SDK to make calls, you must also install the SDK.

Get started with general text embedding

String input

OpenAI compatible

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # If you have not configured environment variables, replace this with your API key
    # If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"  # base_url for Model Studio service
)

completion = client.embeddings.create(
    # If you use a model in the China (Beijing) region, you need to replace the model with: text-embedding-v4
    model="text-embedding-v3",
    input='The quality of the clothes is excellent, very beautiful. It was worth the long wait. I like it and will come back to buy here again.',
    dimensions=1024,# Specify the vector dimension
    encoding_format="float"
)

print(completion.model_dump_json())

Node.js

import OpenAI from "openai";
import process from 'process';

// Initialize the OpenAI client
const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY, // Read from environment variable
    // If you use a model in the China (Beijing) region, you need to replace the baseURL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    baseURL: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
});

async function getEmbedding() {
    try {
        const completion = await openai.embeddings.create({
            // If you use a model in the China (Beijing) region, you need to replace the model with: text-embedding-v4
            model: "text-embedding-v3",
            input: 'The quality of the clothes is excellent, very beautiful. It was worth the long wait. I like it and will come back to buy here again.',
            dimensions: 1024, // Specify the vector dimension
            encoding_format: "float"
        });

        console.log(JSON.stringify(completion, null, 2));
    } catch (error) {
        console.error('Error:', error);
    }
}

getEmbedding();

curl

# ======= Important Note =======
# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings
# If you use a model in the China (Beijing) region, you need to replace the model with: text_embedding_v4
# === Please delete this comment when executing ====

curl --location 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/embeddings' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "text-embedding-v3",
    "input": "The quality of the clothes is excellent, very beautiful. It was worth the long wait. I like it and will come back to buy here again.",  
    "dimension": "1024",  
    "encoding_format": "float"
}'

DashScope

Python

import dashscope
from http import HTTPStatus

# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
resp = dashscope.TextEmbedding.call(
    # If you use a model in the China (Beijing) region, you need to replace the model with: text_embedding_v4
    model=dashscope.TextEmbedding.Models.text_embedding_v3,
    input='The quality of the clothes is excellent, very beautiful. It was worth the long wait. I like it and will come back to buy here again.',
    dimension=1024,# Specify the vector dimension
    output_type="dense&sparse"
)

print(resp) if resp.status_code == HTTPStatus.OK else print(resp)

Java

import java.util.Arrays;
import java.util.concurrent.Semaphore;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.embeddings.TextEmbedding;
import com.alibaba.dashscope.embeddings.TextEmbeddingParam;
import com.alibaba.dashscope.embeddings.TextEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public final class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
        // The China (Beijing) region needs to be replaced with: https://dashscope.aliyuncs.com/api/v1
    }
    public static void basicCall() throws ApiException, NoApiKeyException{
        TextEmbeddingParam param = TextEmbeddingParam
        .builder()
        // The China (Beijing) region needs to be replaced with: TEXT_EMBEDDING_V4
        .model(TextEmbedding.Models.TEXT_EMBEDDING_V3)
        .texts(Arrays.asList("The wind is swift, the sky is high, the apes shriek mournfully", "The islet is clear, the sand is white, the birds fly back", "The boundless forest sheds its leaves shower by shower", "The endless river rolls its waves hour after hour")).build();
        TextEmbedding textEmbedding = new TextEmbedding();
        TextEmbeddingResult result = textEmbedding.call(param);
        System.out.println(result);
    }
  
    public static void callWithCallback() throws ApiException, NoApiKeyException, InterruptedException{
        TextEmbeddingParam param = TextEmbeddingParam
        .builder()
        .model(TextEmbedding.Models.TEXT_EMBEDDING_V3)
        .texts(Arrays.asList("The wind is swift, the sky is high, the apes shriek mournfully", "The islet is clear, the sand is white, the birds fly back", "The boundless forest sheds its leaves shower by shower", "The endless river rolls its waves hour after hour")).build();
        TextEmbedding textEmbedding = new TextEmbedding();
        Semaphore sem = new Semaphore(0);
        textEmbedding.call(param, new ResultCallback<TextEmbeddingResult>() {

          @Override
          public void onEvent(TextEmbeddingResult message) {
            System.out.println(message);
          }
          @Override
          public void onComplete(){
            sem.release();
          }

          @Override
          public void onError(Exception err){
            System.out.println(err.getMessage());
            err.printStackTrace();
            sem.release();
          }
          
        });
        sem.acquire();
    }

  public static void main(String[] args){
    try{
      callWithCallback();
    }catch(ApiException|NoApiKeyException|InterruptedException e){
      e.printStackTrace();
      System.out.println(e);

    }
      try {
        basicCall();
    } catch (ApiException | NoApiKeyException e) {
        System.out.println(e.getMessage());
    }
    System.exit(0);
  }
}

curl

# ======= Important Note =======
# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
# If you use a model in the China (Beijing) region, you need to replace the model with: text_embedding_v4
# === Please delete this comment when executing ====

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "text-embedding-v3",
    "input": {
        "texts": [
        "The quality of the clothes is excellent, very beautiful. It was worth the long wait. I like it and will come back to buy here again."
        ]
    },
    "parameters": {
        "dimension": 1024
    }
}'

String list input

OpenAI compatible

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # If you have not configured environment variables, replace this with your API key
    # If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"  # base_url for Model Studio service
)

completion = client.embeddings.create(
    # If you use a model in the China (Beijing) region, you need to replace the model with: text-embedding-v4
    model="text-embedding-v3",
    input=['The wind is swift, the sky is high, the apes shriek mournfully', 'The islet is clear, the sand is white, the birds fly back', 'The boundless forest sheds its leaves shower by shower', 'The endless river rolls its waves hour after hour'],
    encoding_format="float"
)

print(completion.model_dump_json())

Node.js

import OpenAI from "openai";
import process from 'process';

// Initialize the OpenAI client
const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY, // Read from environment variable
    // If you use a model in the China (Beijing) region, you need to replace the baseURL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    baseURL: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
});

async function getMultipleEmbeddings() {
    try {
        const completion = await openai.embeddings.create({
            // If you use a model in the China (Beijing) region, you need to replace the model with: text-embedding-v4
            model: "text-embedding-v3",
            input: [
                'The wind is swift, the sky is high, the apes shriek mournfully', 
                'The islet is clear, the sand is white, the birds fly back', 
                'The boundless forest sheds its leaves shower by shower', 
                'The endless river rolls its waves hour after hour'
            ],
            encoding_format: "float"
        });

        console.log(JSON.stringify(completion, null, 2));
    } catch (error) {
        console.error('Error:', error);
    }
}

getMultipleEmbeddings();

curl

# ======= Important Note =======
# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings
# If you use a model in the China (Beijing) region, you need to replace the model with: text_embedding_v4
# === Please delete this comment when executing ====

curl --location 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/embeddings' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "text-embedding-v3",
    "input": [
        "The wind is swift, the sky is high, the apes shriek mournfully",
        "The islet is clear, the sand is white, the birds fly back", 
        "The boundless forest sheds its leaves shower by shower", 
        "The endless river rolls its waves hour after hour"
        ],
    "encoding_format": "float"
}'

DashScope

Python

import dashscope
from http import HTTPStatus

# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
DASHSCOPE_MAX_BATCH_SIZE = 25

inputs = ['The wind is swift, the sky is high, the apes shriek mournfully', 'The islet is clear, the sand is white, the birds fly back', 'The boundless forest sheds its leaves shower by shower', 'The endless river rolls its waves hour after hour']

result = None
batch_counter = 0
for i in range(0, len(inputs), DASHSCOPE_MAX_BATCH_SIZE):
    batch = inputs[i:i + DASHSCOPE_MAX_BATCH_SIZE]
    resp = dashscope.TextEmbedding.call(
        # If you use a model in the China (Beijing) region, you need to replace the model with: text_embedding_v4
        model=dashscope.TextEmbedding.Models.text_embedding_v3,
        input=batch,
        dimension=1024 # Specify the vector dimension
    )
    if resp.status_code == HTTPStatus.OK:
        if result is None:
            result = resp
        else:
            for emb in resp.output['embeddings']:
                emb['text_index'] += batch_counter
                result.output['embeddings'].append(emb)
            result.usage['total_tokens'] += resp.usage['total_tokens']
    else:
        print(resp)
    batch_counter += len(batch)

print(result)

Java

import java.util.Arrays;
import java.util.List;
import com.alibaba.dashscope.embeddings.TextEmbedding;
import com.alibaba.dashscope.embeddings.TextEmbeddingParam;
import com.alibaba.dashscope.embeddings.TextEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public final class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
        // The China (Beijing) region needs to be replaced with: https://dashscope.aliyuncs.com/api/v1
    }
    private static final int DASHSCOPE_MAX_BATCH_SIZE = 25;

    public static void main(String[] args) {
        List<String> inputs = Arrays.asList(
                "The wind is swift, the sky is high, the apes shriek mournfully",
                "The islet is clear, the sand is white, the birds fly back",
                "The boundless forest sheds its leaves shower by shower",
                "The endless river rolls its waves hour after hour"
        );

        TextEmbeddingResult result = null;
        int batchCounter = 0;

        for (int i = 0; i < inputs.size(); i += DASHSCOPE_MAX_BATCH_SIZE) {
            List<String> batch = inputs.subList(i, Math.min(i + DASHSCOPE_MAX_BATCH_SIZE, inputs.size()));
            TextEmbeddingParam param = TextEmbeddingParam.builder()
                    // The China (Beijing) region needs to be replaced with: TEXT_EMBEDDING_V4
                    .model(TextEmbedding.Models.TEXT_EMBEDDING_V3)
                    .texts(batch)
                    .build();

            TextEmbedding textEmbedding = new TextEmbedding();
            try {
                TextEmbeddingResult resp = textEmbedding.call(param);
                if (resp != null) {
                    if (result == null) {
                        result = resp;
                    } else {
                        for (var emb : resp.getOutput().getEmbeddings()) {
                            emb.setTextIndex(emb.getTextIndex() + batchCounter);
                            result.getOutput().getEmbeddings().add(emb);
                        }
                        result.getUsage().setTotalTokens(result.getUsage().getTotalTokens() + resp.getUsage().getTotalTokens());
                    }
                } else {
                    System.out.println(resp);
                }
            } catch (ApiException | NoApiKeyException e) {
                e.printStackTrace();
            }
            batchCounter += batch.size();
        }

        System.out.println(result);
    }
}

curl

# ======= Important Note =======
# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
# If you use a model in the China (Beijing) region, you need to replace the model with: text_embedding_v4
# === Please delete this comment when executing ====

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "text-embedding-v3",
    "input": {
        "texts": [
          "The wind is swift, the sky is high, the apes shriek mournfully",
          "The islet is clear, the sand is white, the birds fly back", 
          "The boundless forest sheds its leaves shower by shower", 
          "The endless river rolls its waves hour after hour"
        ]
    },
    "parameters": {
        "dimension": 1024
    }
}'

Plain text file input

The embedding model can generate embedding vectors based on the document you upload. This example uses the texts_to_embedding.txt file.

OpenAI compatible

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # If you have not configured environment variables, replace this with your API key
    # If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"  # base_url for Model Studio service
)
with open('texts_to_embedding.txt', 'r', encoding='utf-8') as f:
    completion = client.embeddings.create(
        # If you use a model in the China (Beijing) region, you need to replace the model with: text-embedding-v4
        model="text-embedding-v3",
        input=f
    )
print(completion.model_dump_json())

Node.js

import OpenAI from "openai";
import process from 'process';
import fs from 'fs/promises';

// Initialize the OpenAI client
const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY, // Read from environment variable
    // If you use a model in the China (Beijing) region, you need to replace the baseURL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    baseURL: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
});

async function getEmbeddingsFromFile() {
    try {
        // Read the file content
        const fileContent = await fs.readFile('texts_to_embedding.txt', 'utf-8');
        
        // Create embedding vectors
        const completion = await openai.embeddings.create({
            // If you use a model in the China (Beijing) region, you need to replace the model with: text-embedding-v4
            model: "text-embedding-v3",
            input: fileContent
        });

        console.log(JSON.stringify(completion, null, 2));
    } catch (error) {
        console.error('Error:', error);
    }
}

getEmbeddingsFromFile();

curl

# ======= Important Note =======
# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/api/v1/embeddings
# If you use a model in the China (Beijing) region, you need to replace the model with: text-embedding-v4
# === Please delete this comment when executing ====

curl --location 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/embeddings' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "text-embedding-v3",
    "input": '"$(cat texts_to_embedding.txt | jq -R -s 'split("\n")[:-1]')"'
}'

DashScope

Python

from http import HTTPStatus
import dashscope
from dashscope import TextEmbedding

# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
with open('texts_to_embedding.txt', 'r', encoding='utf-8') as f:
    resp = TextEmbedding.call(
        # If you use a model in the China (Beijing) region, you need to replace the model with: text_embedding_v4
        model=TextEmbedding.Models.text_embedding_v3,
        input=f
    )

    if resp.status_code == HTTPStatus.OK:
        print(resp)
    else:
        print(resp)

Java

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;
import com.alibaba.dashscope.embeddings.TextEmbedding;
import com.alibaba.dashscope.embeddings.TextEmbeddingParam;
import com.alibaba.dashscope.embeddings.TextEmbeddingResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public final class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
        // The China (Beijing) region needs to be replaced with: https://dashscope.aliyuncs.com/api/v1
    }
    public static void main(String[] args) {
        try (BufferedReader reader = new BufferedReader(new FileReader("<path to the content root of the file>"))) {
            StringBuilder content = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                content.append(line).append("\n");
            }

            TextEmbeddingParam param = TextEmbeddingParam.builder()
                    // The China (Beijing) region needs to be replaced with: TEXT_EMBEDDING_V4
                    .model(TextEmbedding.Models.TEXT_EMBEDDING_V3)
                    .text(content.toString())
                    .build();

            TextEmbedding textEmbedding = new TextEmbedding();
            TextEmbeddingResult result = textEmbedding.call(param);

            if (result != null) {
                System.out.println(result);
            } else {
                System.out.println("Failed to get embedding: " + result);
            }
        } catch (IOException | ApiException | NoApiKeyException e) {
            e.printStackTrace();
        }
    }
}

curl

# ======= Important Note =======
# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
# If you use a model in the China (Beijing) region, you need to replace the model with: text-embedding-v4
# === Please delete this comment when executing ====

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "text-embedding-v3",
    "input": {
        "texts": '"$(cat texts_to_embedding.txt | jq -R -s 'split("\n")[:-1]')"'
    },
    "parameters": {
        "dimension": 1024
    }
}'

Sample output

OpenAI compatible

{ 
  "data": [
    {
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... 
        -0.0028842222,
      ],
      "index": 0,
      "object": "embedding"
    }
  ],
  "model":"text-embedding-v3",
  "object":"list",
  "usage":{"prompt_tokens":26,"total_tokens":26},
  "id":"f62c2ae7-0906-9758-ab34-47c5764f07e2"
}

DashScope

{
    "status_code": 200,
    "request_id": "617b3670-6f9e-9f47-ad57-997ed8aeba6a",
    "code": "",
    "message": "",
    "output": {
        "embeddings": [
            {
                "embedding": [
                    0.09393704682588577,
                    2.4155092239379883,
                    -1.8923076391220093,
                    .,
                    .,
                    .

                ],
                "text_index": 0
            }
        ]
    },
    "usage": {
        "total_tokens": 26
    }
}

Get started with multimodal embedding(Only available in the China (Beijing) region)

You must have obtained an API key and set the API key as an environment variable. If you want to call through SDK, you must also install the DashScope SDK.

Text input

import dashscope
import json
from http import HTTPStatus

text = "Example of a general multimodal representation model"
input = [{'text': text}]
resp = dashscope.MultiModalEmbedding.call(
    model="multimodal-embedding-v1",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    print(json.dumps(resp.output, ensure_ascii=False, indent=4))

Image input

import dashscope
import json
from http import HTTPStatus

image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
resp = dashscope.MultiModalEmbedding.call(
    model="multimodal-embedding-v1",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    print(json.dumps(resp.output, ensure_ascii=False, indent=4))

Video input

The multimodal-embedding-v1 model supports video file input only in URL format. It does not currently support direct input of local videos.

import dashscope
import json
from http import HTTPStatus
# In actual use, please replace the URL with your video URL
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
input = [{'video': video}]
# Call the model API
resp = dashscope.MultiModalEmbedding.call(
    model="multimodal-embedding-v1",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    print(json.dumps(resp.output, ensure_ascii=False, indent=4))

Sample output

{
    "status_code": 200,
    "request_id": "23478d14-55c6-98cc-9706-29d23de742fb",
    "code": "",
    "message": "",
    "output": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.0396728515625,
                    0.00650787353515625,
                    -0.0223388671875,
                    ...
                ],
                "type": "image"
            }
        ]
    },
    "usage": {
        "input_tokens": 0,
        "image_count": 1,
        "duration": 0
    }
}

Usage examples

Implement semantic recommendation

1. Import libraries and configure the API key

Import the required libraries and modules, and configure the API key for subsequent data processing and analysis.

# Import required libraries
import os
import pandas as pd
import pickle
import dashscope
from dashscope import TextEmbedding
import numpy as np
# If you use a model in the China (Beijing) region, you need to replace the base_url with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# Set the DashScope API Key, obtained from environment variables
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

2. Define the embedding function

This function generates text embedding representations using the DashScope API. It accepts a single string or a list of strings, processes them with the text embedding model, and extracts the embedding vectors. If the input is a list, the function returns all embeddings. If the input is a single string, it returns the first embedding vector.

If you use a model in the China (Beijing) region, you need to replace the model with text-embedding-v4.

# Define the function: generate embedding vectors for text
def generate_embeddings(text):
    """
    Generate embedding vectors for input text using DashScope's text-embedding-v3 model.
    Args:
        text (str or list): Input text string or list of strings.
    Returns:
        list: If the input is a string, returns a single embedding vector. If the input is a list, returns multiple vectors.
    """
    rsp = TextEmbedding.call(model=TextEmbedding.Models.text_embedding_v3, input=text)
    # Extract the embedding from the API response
    embeddings = [record['embedding'] for record in rsp.output['embeddings']]
    return embeddings if isinstance(text, list) else embeddings[0]

3. Load the dataset and print the first `n_examples`

Load the dataset and print the publication date and title of the first n_examples.

# Load the dataset
dataset_path = "sampled_file.csv"  # Dataset path
df = pd.read_csv(dataset_path)  # Read the CSV file into a DataFrame
n_examples = 5  # Set the number of examples to display

# Display the publication date and title of the first n_examples samples
print("Displaying the first few samples from the dataset:")
for idx, row in df.head(n_examples).iterrows():
    print("")
    print(f"Publication date: {row['publish_date']}")
    print(f"Title: {row['headline_text']}")

4. Set and load the embedding cache, and define the function to obtain embeddings

Set and load the embedding cache to improve the processing efficiency of embedding vectors in tasks such as recommendation systems. To avoid incurring extra charges when you call the model for vectorization, you can store the vectorized and cached vector file in the project directory.

# Set the embedding cache path (to avoid re-computation)
embedding_cache_path = "recommendations_embeddings_cache.pkl"

# Try to load the cached embedding results. If no cache exists, initialize an empty dictionary.
try:
    embedding_cache = pd.read_pickle(embedding_cache_path)
except FileNotFoundError:
    embedding_cache = {}

# Define the function: obtain text embedding vectors through a caching mechanism
def embedding_from_string(
    string: str,
    embedding_cache=embedding_cache
) -> list:
    """
    Obtain the embedding vector for a given text, using a caching mechanism to avoid re-computation.
    Args:
        string (str): Input text string.
        embedding_cache (dict): Embedding cache dictionary.
    Returns:
        list: The generated embedding vector.
    """
    if string not in embedding_cache.keys():  # If the text is not in the cache
        embedding_cache[string] = generate_embeddings(string)  # Generate and cache the embedding
        # Save the cache to a file
        with open(embedding_cache_path, "wb") as embedding_cache_file:
            pickle.dump(embedding_cache, embedding_cache_file)
    return embedding_cache[string]

5. Calculate the embedding of an example string

Extract the first string from the `description` column of the data frame, calculate its embedding representation, and then output the first 10 elements.

# Calculate the embedding vector of the example string
example_string = df["headline_text"].values[0]  # Select the first text from the dataset
print(f"\nExample text: {example_string}")
example_embedding = embedding_from_string(example_string)  # Obtain the embedding
print(f"\nEmbedding vector of the example text (first 10 dimensions): {example_embedding[:10]}...")
print("\n")

6. Define the recommendation function

By calculating the vector of a string and using the distance based on cosine similarity, this function finds the k strings most similar to the given string and then outputs these strings and their similarity scores.

# Define the recommendation function: output the strings most similar to a given text
def print_recommendations_from_strings(
        strings,  # list[str]: List of input strings
        index_of_source_string,  # int: Index of the source string in the list
        k_nearest_neighbors=1,  # int: Number of similar strings to recommend
):
    """
    Output the k strings most similar to the source string.
    Args:
        strings (list): List of input strings.
        index_of_source_string (int): Index of the source string in the list.
        k_nearest_neighbors (int): Number of neighbors to recommend.
    """
    # Generate embedding vectors for all input strings
    embeddings = [embedding_from_string(string) for string in strings]
    # Obtain the embedding vector of the source string
    query_embedding = embeddings[index_of_source_string]

    # Define the cosine similarity function
    def cosine_similarity(vec1, vec2):
        """
        Calculate the cosine similarity between two vectors.
        Args:
            vec1 (list): Vector 1
            vec2 (list): Vector 2
        Returns:
            float: Cosine similarity value
        """
        return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

    # Calculate the distance (1 - similarity) between the source embedding and all embeddings
    distances = [1 - cosine_similarity(query_embedding, emb) for emb in embeddings]

    # Sort by distance in ascending order to obtain the indices of the nearest neighbors
    indices_of_nearest_neighbors = np.argsort(distances)

    # Print the source string
    query_string = strings[index_of_source_string]
    print(f"Source text: {query_string}")

    # Print the k most similar strings and their similarities
    k_counter = 0
    for i in indices_of_nearest_neighbors:
        if query_string == strings[i]:  # Skip comparison with itself
            continue
        if k_counter >= k_nearest_neighbors:  # Limit the number of recommendations
            break
        k_counter += 1
        print(
            f"""
        --- Recommendation #{k_counter} ---
        Similar text: {strings[i]}
        Similarity: {1 - distances[i]:0.3f}"""
        )
    return indices_of_nearest_neighbors

7. Obtain similar articles

Extract the descriptions of all articles from the dataset, and then retrieve recommendations for the five most similar articles based on articles with specific topics.

# Obtain the list of article titles
article_titles = df["headline_text"].tolist()

# Obtain recommendation results based on a certain text
print("Example of text-based recommendation:")
print("Recommendations for finance-related articles")
recommendations = print_recommendations_from_strings(
    strings=article_titles,  # Input list of article titles
    index_of_source_string=0,  # Select the first text as the source text
    k_nearest_neighbors=5,  # Recommend the 5 most similar texts
)

API reference

General text embedding
- Synchronous API details
Multimodal embedding
Multimodal embedding

Error codes

If the call failed and an error message is returned, see Error messages for troubleshooting.

Limitations

Before you call the embedding model, make sure that the token length of your input does not exceed the limit. The number of Chinese characters is not exactly equivalent to the number of tokens. You can estimate that one Chinese character is approximately one to two tokens, or use the Token Calculator to calculate the exact number.

The following input type and format limits apply to the multimodal embedding API:

Input type	Language/format limit	Length/Size limit
Text	Chinese/English	512 tokens. Text content exceeding 512 tokens will be truncated.
Image	JPG, PNG, BMP	Supports input in Base64 format or as a URL. The maximum acceptable image size is 3 MB.
Video	MP4, MPEG, MPG, WEBM, AVI, FLV, MKV, MOV	The maximum acceptable video size is 10 MB.

The API supports the upload of a single text segment, a single image, or a single video file. It also allows combinations of different types, such as text and image. However, only one combination is allowed per call, and each type of content can be included at most once per call. Files must also meet the length and size requirements.

For information about rate limits, see Rate limits.

Scenarios

Supported models

General text embedding

Multimodal embedding

Model selection suggestions

Preferred models

Get started

Get started with general text embedding

String input

OpenAI compatible

DashScope

String list input

OpenAI compatible

DashScope

Plain text file input

OpenAI compatible

DashScope

Sample output

OpenAI compatible

DashScope

Get started with multimodal embedding(Only available in the China (Beijing) region)

Text input

Image input

Video input

Usage examples

Implement semantic recommendation

1. Import libraries and configure the API key

2. Define the embedding function

3. Load the dataset and print the first n_examples

4. Set and load the embedding cache, and define the function to obtain embeddings

5. Calculate the embedding of an example string

6. Define the recommendation function

7. Obtain similar articles

API reference

General text embedding

Multimodal embedding

Error codes

Limitations

3. Load the dataset and print the first `n_examples`