Batch processing API reference

Model overview

Model name	Data type	Vector dimensions	Maximum lines per request	Maximum input tokens per line	Supported languages
text-embedding-async-v2	32-bit float	1,536	100,000	2,048	Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian
text-embedding-async-v1	32-bit float	1,536	100,000	2,048	Chinese, English, Spanish, French, and Portuguese, Indonesian

Model name	Price (per 1,000 input tokens)	Free quota (Note)	Throttling conditions (Throttling is triggered if any limit is exceeded)
text-embedding-async-v2	CNY 0.0007	20 million tokens for each model Validity: 90 days after you activate Model Studio	1	A user can have a maximum of 50 tasks that are queued or running for the general text embedding asynchronous service. In addition, to prevent resource exhaustion from burst requests, a user can run a maximum of 3 tasks concurrently. Other tasks must wait in the queue.
text-embedding-async-v1

Model name

Price

(per 1,000 input tokens)

Free quota (Note)

Throttling conditions (Throttling is triggered if any limit is exceeded)

RPS limit for task submission API

Number of concurrent processing tasks

text-embedding-async-v2

CNY 0.0007

20 million tokens for each model

Validity: 90 days after you activate Model Studio

A user can have a maximum of 50 tasks that are queued or running for the general text embedding asynchronous service.

In addition, to prevent resource exhaustion from burst requests, a user can run a maximum of 3 tasks concurrently. Other tasks must wait in the queue.

text-embedding-async-v1

Prerequisites

You can call the general text embedding batch processing API using HTTP and the DashScope software development kit (SDK). Before making a call, get an API key and export the API key as an environment variable. To make calls using the SDK, install the DashScope SDK.

HTTP calls

HTTP calls support only asynchronous mode and involve two steps:

Create a task: Send a request to create a task. The request returns a task ID.
Query the result by task ID: Use the task ID from the previous step to query the result generated by the model.

HTTP call endpoint: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding Replace {WorkspaceId} with your actual workspace ID.

Create a task

Request parameters

Headers

Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.Content-Type string (Required)The content type of the request. Must be application/json.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.

If this request header is missing, the error "current user api does not support synchronous calls" is returned.

Request body

model string(Required)The name of the model to call. You can select text-embedding-async-v1 or text-embedding-async-v2.input object (Required)The input for batch vectorization.

Property

url string (Required)The HTTP URL of the file for batch vectorization. Each line contains one entry to be embedded.Text limits:

A single line of a string supports up to 2,048 tokens.
A single request supports a maximum of 100,000 lines of text.
The file size cannot exceed 200 MB.

parameters object (Optional)Parameters for vectorization.

Property

text_type string (Optional)Parameter values:

document (default)
query

After text is converted to vectors, you can use them for downstream tasks, such as retrieval, clustering, and classification. For asymmetric tasks such as retrieval, distinguish between query text (query) and document text (document) for better results. For symmetric tasks such as clustering and classification, you can use the default value document.

curl -X POST 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'X-DashScope-Async: enable' \
    -d '{
    "model": "text-embedding-async-v2",
    "input": {
        "url": "https://modelscope.oss-cn-beijing.aliyuncs.com/resource/text_embedding_file.txt"
    },
    "parameters": {
        "text_type": "query"
    }
}'

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

Successful response
Error response

Save the task_id to query the task status and result.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Query the result by task ID

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Request parameters

Headers

Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Path parameters

task_id string (Required)The ID of the task.

Query task result

Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.

If you use a model in the Singapore region, replace base_url with https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx, where {WorkspaceId} is your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobjectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

submit_time stringThe time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.url stringThe URL of the output file generated by the model.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

usage objectStatistics for the output information. Only successful results are counted.

Property

total_tokensintegerThe number of tokens in the input content for the request. This number is calculated based on the tokens that are parsed by the model's tokenizer from the input text file.

request_id stringUnique request identifier for tracing and troubleshooting.

Task succeeded
Task running
Task failed

Task data, such as the task status and result URL, is retained for only 24 hours and then automatically deleted. You must save the generated output file promptly.

{
    "request_id":"<Your Request ID>",
    "output":{
        "task_id":"<Your Task ID>",
        "task_status":"SUCCEEDED",
        "submit_time":"2025-02-20 14:37:13.328",
        "scheduled_time":"2025-02-20 14:37:13.352",
        "end_time":"2025-02-20 14:37:14.159",
        "url":"<URL containing the output result>"
    },
    "usage":{
        "total_tokens":258
    }
}

If a task fails, its status is set to FAILED. The code and message fields indicate the reason for the failure.

{
  "request_id": "<Your Request ID>"
  "output": {
        "task_id": "<Your Task ID>",
        "task_status": "FAILED",
        "submit_time":"2025-02-20 15:57:19.039",
        "scheduled_time":"2025-02-20 15:57:19.059",
        "end_time":"2025-02-20 15:57:19.418",
        "code": "xxx",
         "message": "xxxxxx"
  }
}

Dashscope

To avoid errors, make sure that you have installed the latest version of the DashScope SDK. For more information, see Install the SDK. The DashScope SDK is available in Python and Java. The parameter names for the SDK and HTTP API are mostly the same. The parameter structure depends on the SDK encapsulation for each language. For parameter descriptions, see Wanxiang text-to-image V2. Because the model requires a long processing time, the underlying service is provided asynchronously. The SDK is encapsulated to support both synchronous and asynchronous calls.

Request body

model string(Required)The name of the model to call. You can select text-embedding-async-v1 or text-embedding-async-v2.url string (Required)The HTTP URL of the file for batch vectorization. Each line contains one entry to be vectorized.Text limits:

A single line of a string supports up to 2,048 tokens.
A single request supports a maximum of 100,000 lines of text.
The file size cannot exceed 200 MB.

text_type string(Optional)After text is converted to vectors, you can use them for downstream tasks, such as retrieval, clustering, and classification. For asymmetric tasks such as retrieval, distinguish between query text (query) and document text (document) for better results. For symmetric tasks such as clustering and classification, you can use the default value document.

Synchronous call
Asynchronous call

Python

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

result = BatchTextEmbedding.call(BatchTextEmbedding.Models.text_embedding_async_v1,
                                 url="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241016/nigwvr/text_embedding_file.txt",
                                 text_type="document")
print(result)

Python

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

# Create an asynchronous task.
def create_async_task():
    rsp = BatchTextEmbedding.async_call(model=BatchTextEmbedding.Models.text_embedding_async_v1,
                                        url="https://modelscope.oss-cn-beijing.aliyuncs.com/resource/text_embedding_file.txt",
                                        text_type="document")
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output)
        print(rsp.usage)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))
    return rsp

# Get information about the asynchronous task.
def fetch_task_status(task):
    status = BatchTextEmbedding.fetch(task)
    print(status)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

# Wait for the asynchronous task to complete. The SDK encapsulates polling logic and waits until the task is finished.
def wait_task(task):
    rsp = BatchTextEmbedding.wait(task)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

# Cancel the asynchronous task. Only tasks in the PENDING state can be canceled.
def cancel_task(task):
    rsp = BatchTextEmbedding.cancel(task)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    task_info = create_async_task()
    fetch_task_status(task_info)
    wait_task(task_info)

Response parameters

status_code stringThe status code of the request, which indicates the execution result. For example, 200 indicates success. For more information, see Error messages.request_id stringA unique identifier for the request. You can use it to trace request details and troubleshoot issues.code stringThe error code for a failed request. This parameter is empty for successful requests. For more information, see Error messages.message stringThe detailed information for a failed request. This parameter is empty for successful requests. For more information, see Error messages.outputobjectTask output information.

Properties

task_idstringA unique identifier for the task. You can use it to trace task details and troubleshoot issues.task_statusstringThe task status.

SUCCEEDED: The task was successful.
FAILED: The task failed.
CANCELED: The task was canceled.
PENDING: The task is in the queue.
SUSPENDED: The task is suspended.
RUNNING: The task is being processed.

urlstringThe URL that contains the embedding results. This parameter is empty if the task fails.submit_timestringThe time when the task was submitted.

This field is not included in the response of the Java SDK.

scheduled_timestringThe time when the task was scheduled.

This field is not included in the response of the Java SDK.

end_timestringThe time when the task finished processing.

This field is not included in the response of the Java SDK.

codestringIf the task fails, this parameter indicates the reason for the failure. This parameter is not returned for successful executions.messagestringIf the task fails, this parameter provides detailed information about the failure. This parameter is not returned for successful executions.

usageobjectProperty

Details

total_tokens integerThe number of tokens in the input content for the request. This number is calculated based on the tokens that are parsed by the model's tokenizer from the input string.

Synchronous call
Asynchronous call

Successful response
Error response

{
    "status_code": 200,
    "request_id": "<Your Request ID>",
    "code": null,
    "message": "",
    "output": {
        "task_id": "<Your Task ID>",
        "task_status": "SUCCEEDED",
        "url": "<URL containing the output result>",
        "submit_time": "2023-09-07 10:22:52.459",
        "scheduled_time": "2023-09-07 10:22:52.481",
        "end_time": "2023-09-07 10:22:53.419"
    },
    "usage": {
        "total_tokens": 384
    }
}

Request failed

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"<Your Request ID>"
}

Task execution failed

{
    "status_code": 200,
    "request_id": "<Your Request ID>",
    "code": null,
    "message": "",
    "output": {
        "task_id": "<Your Task ID>",
        "task_status": "FAILED",
        "url": "null",
        "submit_time": "2023-09-07 10:22:52.459",
        "scheduled_time": "2023-09-07 10:22:52.481",
        "end_time": "2023-09-07 10:22:53.419"
        "code": "InvalidFile.TypeNotTxt",
        "message": "File type should be txt"
    },
    "usage": null
}

Successful response
Error response

{
    "status_code": 200,
    "request_id": "<Your Request ID>",
    "code": null,
    "message": "",
    "output": {
        "task_id": "<Your Task ID>",
        "task_status": "SUCCEEDED",
        "url": "<URL containing the output result>",
        "submit_time": "2025-02-21 13:51:26.465",
        "scheduled_time": "2025-02-21 13:51:26.507",
        "end_time": "2025-02-21 13:51:27.273"
    },
    "usage": {
        "total_tokens": 384
    }
}

Request failed

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"<Your Request ID>"
}

Task execution failed

{
    "status_code": 200,
    "request_id": "<Your Request ID>",
    "code": null,
    "message": "",
    "output": {
        "task_id": "<Your Task ID>",
        "task_status": "FAILED",
        "url": "null",
        "submit_time": "2023-09-07 10:22:52.459",
        "scheduled_time": "2023-09-07 10:22:52.481",
        "end_time": "2023-09-07 10:22:53.419"
        "code": "InvalidFile.TypeNotTxt",
        "message": "File type should be txt"
    },
    "usage": null
}

FAQ

Input file limits

The input file must be a text file encoded in UTF-8. Each line contains a string for which a text vector is computed. The system processes the input line by line and includes the corresponding line number and the generated embedding result in the output file.
A single file cannot exceed 200 MB.
The number of text lines in a single request cannot exceed 100,000.
The content of each line cannot exceed 2,048 tokens.
Blank lines, which are lines that do not contain any characters, are automatically skipped by the system, and their text vectors are not computed. However, the line numbers of these blank lines are retained in the output file to facilitate result mapping.

Output file format

When the task is successfully completed, the submitted input data is converted into vector results and stored in an output file. To save storage space and facilitate downloading, the output file is compressed into the .gz format. After you download the file, you can decompress it to obtain the text output file.
Task data, such as the task status and result URL, is retained for only 24 hours and then automatically deleted. You must save the output file that contains the task results promptly.
The output file that is generated by the model after vectorization is a JSONL file. Each line is a complete JSON structure that contains the vectorized output for a specific line from the input file.

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

Throttling

To ensure fair use, basic throttling is applied to general text embedding models. If you exceed the call limits, your API requests fail due to throttling. You must wait until the conditions are met before you can make another call. For detailed throttling conditions for each model, see Throttling.

​Model overview

​Prerequisites

​HTTP calls

​Create a task

Request parameters

Headers

Request body

Response parameters

​Query the result by task ID

Request parameters

Headers

Path parameters

Response parameters

​Dashscope

Request body

Response parameters

​FAQ

​Input file limits

​Output file format

​Error codes

​Throttling

Model overview

Prerequisites

HTTP calls

Create a task

Query the result by task ID

Dashscope

FAQ

Input file limits

Output file format

Error codes

Throttling