同步接口API详情 - 阿里云百炼

模型概览

北京
新加坡

模型名称	向量维度	最大行数	单行最大Token数	单价（每千输入Token）	支持语种	免费额度（注）
qwen3.7-text-embedding	2560、2,048、1,536、1,024（默认）、768、512、256	20	128,000	0.0005元	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等201种主流语种与方言	各100万Token有效期：百炼开通后90天内
text-embedding-v4 属于Qwen3-Embedding系列	2,048、1,536、1,024（默认）、768、512、256、128、64	10	8,192	0.0005元Batch调用：0.00025元	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种及多种编程语言
text-embedding-v3	1,024（默认）、768、512、256、128或64	10	8,192	0.0005元Batch调用：0.00025元	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等50+主流语种
text-embedding-v2	1,536	25	2,048	0.0007元Batch调用：0.00035元	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语	各50万Token有效期：百炼开通后90天内
text-embedding-v1	1,536	25	2,048	0.0007元Batch调用：0.00035元	中文、英语、西班牙语、法语、葡萄牙语、印尼语	各50万Token有效期：百炼开通后90天内

模型名称	向量维度	最大行数	单行最大Token数	单价（每千输入Token）	支持语种	免费额度
qwen3.7-text-embedding	2560、2,048、1,536、1,024（默认）、768、512、256	20	128,000	0.000525元	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等201种主流语种与方言	无免费额度
text-embedding-v4 属于Qwen3-Embedding系列	2,048、1,536、1,024（默认）、768、512、256、128、64	10	8,192	0.000514元	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等100+主流语种及多种编程语言	无免费额度
text-embedding-v3	1,024（默认）、768、512	10	8,192	0.000514元	中文、英语、西班牙语、法语、葡萄牙语、印尼语、日语、韩语、德语、俄罗斯语等50+主流语种	50万Token有效期：百炼开通后90天内

关于模型限流，请参考限流。

前提条件

若熟悉OpenAI生态，可使用兼容API快速迁移；DashScope API则提供更丰富的独有特性。请根据您的需求选择。您需要已获取与配置 API Key并配置API Key到环境变量。如果通过SDK调用，还需要安装DashScope SDK。请将示例代码中的 DASHSCOPE_API_HOST 替换为获取的 API Host。

OpenAI兼容

公共云

使用SDK调用时需配置的base_url：https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1使用HTTP方式调用时需配置的endpoint：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求体

modelstring必选调用的模型名称，参考模型概览表格中的模型名称进行选择。inputarray<string> 或 string 或 file必选输入待处理的文本。可以是字符串（string）、字符串列表（array）或文件（file）。不同模型版本支持的文本长度和批量大小不同，具体如下：

qwen3.7-text-embedding 模型：
- 输入为字符串：最长支持 128,000 Token。
- 输入为字符串列表或文件：最多支持 20 条（行），每条（行）最长支持 128,000 Token。
text-embedding-v3 / v4 模型：
- 输入为字符串：最长支持 8,192 Token。
- 输入为字符串列表或文件：最多支持 10 条（行），每条（行）最长支持 8,192 Token。
text-embedding-v1 / v2 模型：
- 输入为字符串：最长支持 2,048 Token。
- 输入为字符串列表或文件：最多支持 25 条（行），每条（行）最长支持 2,048 Token。

dimensions integer 可选指定的向量维度，必须为以下值之一：2560（仅适用于qwen3.7-text-embedding）、2048（仅适用于text-embedding-v4）、1536（仅适用于text-embedding-v4）1024、768、512、256、128 或 64，默认值为1024。encoding_format string 可选用于控制返回的Embedding格式，入参支持float和base64，出参的Embedding数据也支持float和base64两种格式。实际返回格式取决于请求路由到的网关：

老网关：无论encoding_format设置为float还是base64，均只返回float类型数据，不支持输出base64数据。
新网关：
- 短请求：按encoding_format设置的格式返回数据。
- 长请求：内部路由到老网关，仅返回float类型数据。

输入字符串
输入字符串列表
输入文件

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请在此处用您的API Key进行替换
    # 以下为华北2（北京）地域的URL，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
)

completion = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input='衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买',
    dimensions=1024, # 指定向量维度（仅 qwen3.7-text-embedding、text-embedding-v3及 text-embedding-v4支持该参数）
    encoding_format="float"
)

print(completion.model_dump_json())

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请在此处用您的API Key进行替换
    # 以下为华北2（北京）地域的URL，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
)

completion = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input=['风急天高猿啸哀', '渚清沙白鸟飞回', '无边落木萧萧下', '不尽长江滚滚来'],
    dimensions=1024,# 指定向量维度（仅 qwen3.7-text-embedding、text-embedding-v3及 text-embedding-v4支持该参数）
    encoding_format="float"
)

print(completion.model_dump_json())

Python
Java
curl

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请在此处用您的API Key进行替换
    # 以下为华北2（北京）地域的URL，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
)
# 确保将 'texts_to_embedding.txt' 替换为您自己的文件名或路径
with open('texts_to_embedding.txt', 'r', encoding='utf-8') as f:
    completion = client.embeddings.create(
        model="qwen3.7-text-embedding",
        input=f,
        dimensions=1024,# 指定向量维度（仅 qwen3.7-text-embedding、text-embedding-v3及 text-embedding-v4支持该参数）
        encoding_format="float"
    )
print(completion.model_dump_json())

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.embeddings.CreateEmbeddingResponse;
import com.openai.models.embeddings.EmbeddingCreateParams;

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;
import java.nio.file.Paths;

public class Main {
    public static void main(String[] args) {
        // 创建客户端，使用环境变量中的API密钥
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 以下为华北2（北京）地域的URL，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的URL不同。
                .baseUrl("https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1")
                .build();

        // 确保将 'texts_to_embedding.txt' 替换为您自己的文件名或绝对路径
        String filePath = "/src/main/java/org/example/text_to_embedding.txt";

        try {
            // 读取文件内容
            StringBuilder fileContent = new StringBuilder();
            try (BufferedReader reader = new BufferedReader(new FileReader(filePath))) {
                String line;
                while ((line = reader.readLine()) != null) {
                    fileContent.append(line).append("\n");
                }
            }

            // 创建向量化请求参数
            EmbeddingCreateParams params = EmbeddingCreateParams.builder()
                    .model("qwen3.7-text-embedding")
                    .input(EmbeddingCreateParams.Input.ofString(fileContent.toString()))
                    // 指定向量维度（仅 qwen3.7-text-embedding、text-embedding-v3及 text-embedding-v4支持该参数）
                    .dimensions(1024)
                    .build();

            // 发送请求并获取响应
            CreateEmbeddingResponse response = client.embeddings().create(params);
            System.out.println(response);

        } catch (IOException e) {
            System.err.println("读取文件时出错：" + e.getMessage());
            e.printStackTrace();
        } catch (Exception e) {
            System.err.println("请求出错，请查看错误码对照网页：");
            System.err.println("https://help.aliyun.com/zh/model-studio/faq-about-alibaba-cloud-model-studio?spm=a2c4g.11186623.help-menu-2400256.d_0_17_0.18733a66lTrcHv#1c38f58abfcml");
            System.err.println("错误详情：" + e.getMessage());
            e.printStackTrace();
        }
    }
}

确保将 'texts_to_embedding.txt' 替换为您自己的文件名或路径

FILE_CONTENT=$(cat texts_to_embedding.txt | jq -Rs .)
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3.7-text-embedding",
    "input": ['"$FILE_CONTENT"'],
    "dimensions": 1024,
    "encoding_format": "float"
}'

响应对象

dataarray任务输出信息。

属性

embeddinglist本次调用返回object对象的value，类型是元素为float数据的数组，包含具体Embedding向量。indexinteger本结构中的算法结果对应的输入文字在输入数组中的索引值。objectstring本次调用返回的object对象类型，默认为embedding。

modelstring本次调用的模型名。objectstring本次调用返回的data类型，默认为list。usageobject本次请求的 Token 用量。向量模型只有输入没有输出，因此 prompt_tokens 与 total_tokens 的取值始终相同。

属性

prompt_tokensinteger本次请求输入内容对应的 Token 数目。取值与 total_tokens 相同。total_tokens integer本次请求消耗的 Token 总数，用于计量计费。Token 数目按输入字符串被模型 Tokenizer 解析后的结果统计，与自行估算的字符数或词数可能不一致。

idstring请求唯一标识。可用于请求明细溯源和问题排查。

{
  "data": [
    {
      "embedding": [
        -0.0695386752486229, 0.030681096017360687, ...
      ],
      "index": 0,
      "object": "embedding"
    },
    ...
    {
      "embedding": [
        -0.06348952651023865, 0.060446035116910934, ...
      ],
      "index": 5,
      "object": "embedding"
    }
  ],
  "model": "qwen3.7-text-embedding",
  "object": "list",
  "usage": {
    "prompt_tokens": 184,
    "total_tokens": 184
  },
  "id": "73591b79-d194-9bca-8bb5-xxxxxxxxxxxx"
}

DashScope

公共云

使用SDK调用时需配置的base_url：https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1使用HTTP方式调用时需配置的endpoint：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求体

modelstring必选调用的模型，参考模型概览表格中的模型名称进行选择。inputstring或array<string>必选输入待处理的文本。可以是字符串（string）、字符串列表（array）或文件（file）。不同模型版本支持的文本长度和批量大小不同，具体如下：

qwen3.7-text-embedding 模型：
- 输入为字符串：最长支持 128,000 Token。
- 输入为字符串列表或文件：最多支持 20 条（行），每条（行）最长支持 128,000 Token。
text-embedding-v3 / v4 模型：
- 输入为字符串：最长支持 8,192 Token。
- 输入为字符串列表或文件：最多支持 10 条（行），每条（行）最长支持 8,192 Token。
text-embedding-v1 / v2 模型：
- 输入为字符串：最长支持 2,048 Token。
- 输入为字符串列表或文件：最多支持 25 条（行），每条（行）最长支持 2,048 Token。

text_type string可选

通过 HTTP 调用时，请将 text_type放入parameters对象中。

文本转换为向量后可以应用于检索、聚类、分类等下游任务，对检索这类非对称任务为了达到更好的检索效果建议区分查询文本（query）和底库文本（document）类型，入库、聚类、分类等对称任务可以不用特殊指定，采用系统默认值document即可。dimension integer 可选

通过 HTTP 调用时，请将 dimension放入parameters对象中。

指定的向量维度，必须为以下值之一：2560（仅适用于qwen3.7-text-embedding）、2048（仅适用于text-embedding-v4）、1536（仅适用于text-embedding-v4）1024、768、512、256、128 或 64，默认值为1024。output_type string 可选

通过 HTTP 调用时，请将 output_type放入parameters对象中。

用户指定输出离散向量表示只适用于qwen3.7-text-embedding、``text-embedding-v3与text-embedding-v4模型，取值在dense、sparse、dense&sparse之间，默认取dense，只输出连续向量。instruct string 可选添加自定义任务说明，可用于指导模型理解查询意图。建议使用英文撰写，通常可带来约 1%–5% 的效果提升。该参数仅在 text_type 取值为 query 时生效，并按输入文本的条数计入 Token 用量。text_type 取值为 document 或未设置 text_type 时，该参数不生效，也不计入 Token 用量。

输入字符串
输入字符串列表
输入文件

Python

import dashscope
from http import HTTPStatus
# 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

resp = dashscope.TextEmbedding.call(
    model="qwen3.7-text-embedding",
    input='衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买',
    dimension=1024,  # 指定向量维度（仅 qwen3.7-text-embedding、text-embedding-v3及 text-embedding-v4支持该参数）
    output_type="dense&sparse"
)

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

Python

import dashscope
from http import HTTPStatus
# 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

DASHSCOPE_MAX_BATCH_SIZE = 10

inputs = ['风急天高猿啸哀', '渚清沙白鸟飞回', '无边落木萧萧下', '不尽长江滚滚来']

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(
        model="qwen3.7-text-embedding",
        input=batch,
        dimension=1024  # 指定向量维度（仅 qwen3.7-text-embedding、text-embedding-v3及 text-embedding-v4支持该参数）
    )
    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)

Python
Java
curl

from http import HTTPStatus
from dashscope import TextEmbedding
# 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

with open('texts_to_embedding.txt', 'r', encoding='utf-8') as f:
    resp = TextEmbedding.call(
        model="qwen3.7-text-embedding",
        input=f,
        dimension=1024 # 指定向量维度（仅 qwen3.7-text-embedding、text-embedding-v3及 text-embedding-v4支持该参数）
    )

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

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 {
    public static void main(String[] args) {
        // 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        try (BufferedReader reader = new BufferedReader(new FileReader("<文件所来自的内容根的路径>"))) {
            StringBuilder content = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                content.append(line).append("\n");
            }

            TextEmbeddingParam param = TextEmbeddingParam.builder()
                    .model("qwen3.7-text-embedding")
                    .text(content.toString())
                    .parameter("dimension", 1024)  // 指定向量维度（仅 qwen3.7-text-embedding、text-embedding-v3及 text-embedding-v4支持该参数）
                    .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();
        }
    }
}

确保将 'texts_to_embedding.txt' 替换为您自己的文件名或路径

FILE_CONTENT=$(cat texts_to_embedding.txt | jq -Rs .)
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3.7-text-embedding",
    "input": {
        "texts": ['"$FILE_CONTENT"']
    },
    "parameters": {
        "dimension": 1024,
        "output_type": "dense"
    }
}'

响应对象

status_code string状态码，表示请求的执行结果（如 200 表示成功）。request_id string请求唯一标识。可用于请求明细溯源和问题排查。code string请求失败，表示错误码，成功时返回参数中该参数为空。message string请求失败，表示失败详细信息，成功时返回参数中该参数为空。outputobject任务输出信息。

属性

embeddingsarray本次请求的算法输出内容，是一个由结构组成的数组，每一个数组中包含一个对应的输入 text 的算法输出内容。

属性

sparse_embedding array对应字符串的算法输出离散向量表示（sparse embedding仅适用于text-embedding-v3与text-embedding-v4）。

属性

index integer词汇或字符在词汇表中的位置索引。value float表示该 Token 的权重或重要性分数，值越高，表示该 Token 在当前文本上下文中的重要性或相关性越大。token string实际的文本单元或词汇表中的词。

embedding array对应字符串的算法输出连续向量表示（dense embedding)。text_index integer本结构中的算法结果对应的输入文字在输入数组中的索引值。

usageobject本次请求的 Token 用量。向量模型只有输入没有输出，因此该对象中各字段的取值始终相同。

属性

input_tokens integer本次请求输入内容对应的 Token 数目。取值与 total_tokens 相同。仅 qwen3.7-text-embedding 返回该参数。text-embedding-v4、text-embedding-v3、text-embedding-v2 和 text-embedding-v1 不返回该参数。total_tokens integer本次请求消耗的 Token 总数，用于计量计费。Token 数目按输入字符串被模型 Tokenizer 解析后的结果统计，与自行估算的字符数或词数可能不一致。设置 instruct 且 text_type 取值为 query 时，instruct 会按输入文本的条数重复计入 Token 用量。

{   "status_code": 200,
    "request_id": "1ba94ac8-e058-99bc-9cc1-7fdb37940a46",
    "code": "",
    "message": "",
    "output":{
        "embeddings": [
          {
             "sparse_embedding":[
               {"index":7149,"value":0.829,"token":"风"},
               .....
               {"index":111290,"value":0.9004,"token":"哀"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 0
          },
          {
             "sparse_embedding":[
               {"index":246351,"value":1.0483,"token":"渚"},
               .....
               {"index":2490,"value":0.8579,"token":"回"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 1
          },
          {
             "sparse_embedding":[
               {"index":3759,"value":0.7065,"token":"无"},
               .....
               {"index":1130,"value":0.815,"token":"下"}],
             "embedding": [-0.006929283495992422,-0.005336422007530928, ...],
             "text_index": 2
          },
          {
             "sparse_embedding":[
               {"index":562,"value":0.6752,"token":"不"},
               .....
               {"index":1589,"value":0.7097,"token":"来"}],
             "embedding": [-0.001945948973298072,-0.005336422007530928, ...],
             "text_index": 3
          }
        ]
    },
    "usage":{
        "total_tokens":27
    }
}

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

​模型概览

​前提条件

​OpenAI兼容

请求体

响应对象

​DashScope

请求体

响应对象

​错误码

模型概览

前提条件

OpenAI兼容

DashScope

错误码