How to call the Qwen-MT-Image image translation API - Alibaba Cloud Model Studio

Qwen-MT-Image accurately translates text in images and preserves the original layout. The model also supports custom features such as domain hints, sensitive word filtering, and terminology intervention.

Important

This document applies only to the China (Beijing) region. You must use an API key from this region.

Model overview

Examples

Source language: English

Japanese

Portuguese

Arabic

Model and pricing

The image translation feature supports translation between Chinese or English and other languages, but does not support direct translation between non-Chinese/English languages, such as from Japanese to Korean. For more information, see Supported languages.

Model	Unit price	Rate limit (shared by Alibaba Cloud account and RAM users)
		Task submission API RPS limit	Number of concurrent tasks
qwen-mt-image	$0.000431/image	1	2

Billing rules

Billing method: You are billed based on the number of successfully generated images. You are charged after a task succeeds (the task_status is SUCCEEDED) and an image is generated.
Note: If an image contains no translatable text or if no text remains in the non-subject area after subject identification is enabled, the task still succeeds and is billed as normal. In this case, the API returns the message No text detected for translation.

HTTP

You must obtain an API key and set the API key as an environment variable.

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

Because image translation takes time, the HTTP API uses an asynchronous mode. The call process involves two steps:

Create a task and obtain a task ID: Send a request to create a task. The request returns a task_id.
Query the task result using the task ID: Use the task_id to poll the task status until the task is complete and you retrieve the image URL.

Step 1: Create a task and get a task ID

Note

After a task is created, use the returned task_id to query the result by polling. The task_id is valid for 24 hours. Do not create the task repeatedly.

Request parameters	Image translation `curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \ --header 'X-DashScope-Async: enable' \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "qwen-mt-image", "input": { "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250916/arpjoo/p1000391.webp", "source_lang": "en", "target_lang": "ja" } }'`
Request headers
Content-Type `string` (Required) The content type of the request. Set this parameter to `application/json`.
Authorization `string` (Required) The identity authentication credentials for the request. This API uses an Model Studio API key for identity authentication. Example: Bearer sk-xxxx.
X-DashScope-Async `string` (Required) The asynchronous processing configuration parameter. HTTP requests support only asynchronous processing. You must set this parameter to `enable`. Important If this request header is missing, the error message "current user api does not support synchronous calls" is returned.
Request body
model `string` (Required) The model name. Set this parameter to `qwen-mt-image`.
input `object` (Required) The input parameter object. It contains the following fields: Properties image_url `string` (Required) A publicly accessible URL of the image. HTTP and HTTPS protocols are supported. Format limit: JPG, JPEG, PNG, BMP, PNM, PPM, TIFF, or WEBP Dimension limit: The width and height of the image must be between 15 and 8,192 pixels. The aspect ratio must be between 1:10 and 10:1. Size limit: No more than 10 MB If the URL contains non-ASCII characters, such as Chinese characters, you must URL-encode the URL before you pass it in the request. URL encoding `from urllib.parse import quote # Replace the following URL with the one you need to encode url = "https://example.com/search?q=test&page=1" encoded_url = quote(url, safe=':/?#[]@!$&\'()+,;=%') print(f"Original URL: {url}") print(f"Encoded URL: {encoded_url}")` Example: `https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250916/arpjoo/p1000391.webp` source_lang* `string` (Required) The source language. Supported values: The full language name, language code, or `auto` (for automatic detection). The value is case-insensitive. Limit: Must be different from `target_lang`. At least one of the source or target languages must be Chinese or English. Example: `Chinese`, `en`, or `auto` target_lang `string` (Required) Target language. Supported values: The full language name or language code. The value is case-insensitive. Limit: Must be different from `source_lang`. At least one of the source or target languages must be Chinese or English. Example: `Chinese` or `en` ext `object` (Optional) Optional extended fields. Properties domainHint `string` (Optional) A domain hint. To make the translation style more suitable for a specific domain, use English to describe the scenario, translation style, and other requirements. To ensure translation quality, the hint should not exceed 200 English words. Important Domain hints currently support only English. Example: These sentences are from seller-buyer conversations on a B2C ecommerce platform. Translate them into clear, engaging customer service language, ensuring the translation is appropriate for handling potential issues or disputes. sensitives `array` (Optional) Configures sensitive words to filter from the image text before translation. The filter performs an exact match and is case-sensitive. The language of the sensitive words can be different from the source language. All source languages and target languages are supported. To ensure translation quality, add no more than 50 sensitive words per request. Example: ["10% off entire store", "7-day no-questions-asked return"] terminologies `array` (Optional) Terminology intervention. Sets the translation for specific terms to meet the translation requirements of a specific domain. The language of the term pair must correspond to `source_lang` and `target_lang`. Properties src `string` (Required) The source text of the term. The language must be the same as `source_lang`. tgt `string` (Required) The target text of the term. The language must be the same as `target_lang`. Example: [{"src": "Application Program Interface", "tgt": "API"}, {"src": "Machine Learning", "tgt": "ML"}] config `object` (Optional) Properties skipImgSegment `bool` (Optional) Controls whether to skip subject detection and translate text on subjects in the image, such as people, products, or logos. `false`: (Default) Performs subject detection and does not translate text on subjects. `true`: Does not perform subject detection and translates all text, including text on subjects.

Response parameters	Successful 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" }` Error response The task creation failed. For more information, see Error messages to resolve the issue. `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxx" }`
output `object` Task output information. Properties task_id `string` The task ID. The query is valid for 24 hours. task_status `string` The task status. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: The task does not exist or its status cannot be determined.
request_id `string` The unique request ID. You can use this ID to trace and troubleshoot issues.
message `string` The detailed information about a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.
code `string` The error code for a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

Step 2: Query the result using the task ID

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Note

The model takes about 15 seconds to process a request. Use a polling mechanism with a reasonable query interval, such as 5 seconds, to retrieve the result.
The task_id is valid for 24 hours. If the ID does not exist or has expired, the task status is returned as UNKNOWN.
The url returned for a successful task is valid for 24 hours. Download and save the image promptly.

Request parameters	Query task result Replace `86ecf553-d340-4e21-xxxxxxxxx` with the actual task_id. `curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
Request headers
Authorization `string` (Required) The identity authentication credentials for the request. This API uses an Model Studio API key for identity authentication. Example: Bearer sk-xxxx.
URL path parameters
task_id `string` (Required) The task ID.

Response parameters	Task successful Task data, such as the task status and image URLs, is retained for only 24 hours and is automatically purged after this period. You must save the generated images promptly. `{ "request_id": "5fec62eb-bf94-91f8-b9f4-f7f758e4e27e", "output": { "task_id": "72c52225-8444-4cab-ad0c-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2025-08-13 18:11:16.954", "scheduled_time": "2025-08-13 18:11:17.003", "end_time": "2025-08-13 18:11:23.860", "image_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx?Expires=xxx" }, "usage": { "image_count":1 } }` Task failed If a task fails, task_status is set to FAILED, and an error code and message are provided. For more information, see Error messages to resolve the issue. `{ "request_id": "daad9007-6acd-9fb3-a6bc-d55902b9c9ff", "output": { "task_id": "fe8aa114-d9f1-4f76-b598-xxxxxx", "task_status": "FAILED", "submit_time": "2025-08-20 09:54:21.911", "scheduled_time": "2025-08-20 09:54:21.984", "end_time": "2025-08-20 12:55:00.818", "code": "InternalError", "message": "xxxxxx" } }`
output `object` Task output information. Properties task_id `string` The task ID. The query is valid for 24 hours. task_status `string` The task status. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: The task does not exist or its status cannot be determined. submit_time `string` The time when the task was submitted. The time is in the UTC+8 time zone. The format is YYYY-MM-DD HH:mm:ss.SSS. scheduled_time `string` The time when the task started running. The time is in the UTC+8 time zone. The format is YYYY-MM-DD HH:mm:ss.SSS. end_time `string` The time when the task was completed. The time is in the UTC+8 time zone. The format is YYYY-MM-DD HH:mm:ss.SSS. image_url `string` The URL of the image generated by the model. The image has the same dimensions as the source image and is in JPG format. The URL is valid for 24 hours. Download and save the image promptly. code `string` The error code for a failed request. This parameter is not returned if the request is successful. For more information, see Error messages. message `string` The detailed information about the request failure. For more information, see Error messages. This parameter is usually not returned for successful requests. It is returned only when the image contains no translatable text, such as when no text remains after subject identification. In this case, the request still succeeds and is billed as normal, but the message `No text detected for translation` is returned.
usage `object` Usage statistics. These statistics are counted only for successful tasks. Properties image_count `integer` The number of images generated by the model. The value is fixed at 1.
request_id `string` The unique request ID. You can use this ID to trace and troubleshoot issues.

Supported languages

When you translate an image, at least one of the source or target languages must be Chinese or English. Direct translation between two non-Chinese or non-English languages, such as from Japanese to Korean, is not supported. If you are unsure of the source language, you can set source_lang to auto for automatic detection.

Language	Code	As source language	As target language
Chinese	zh	Supported	Supported
English	en	Supported	Supported
Korean	ko	Supported	Supported
Japanese	ja	Supported	Supported
Russian	ru	Supported	Supported
Spanish	es	Supported	Supported
French	fr	Supported	Supported
Portuguese	pt	Supported	Supported
Italian	it	Supported	Supported
Germany	de	Supported	Not supported
Vietnamese	vi	Supported	Supported
Malay	ms	Not supported	Supported
Thai	th	Not supported	Supported
Indonesian	id	Not supported	Supported
Arabian	ar	Not supported	Supported

Configure access permission

Images are stored in Object Storage Service (OSS). The links allow public access and are valid for only 24 hours. If your business system cannot access OSS links because of security policies, you can add the following OSS domain names to your network access whitelist.

dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

Error codes

If a call fails, see Error messages for troubleshooting.

FAQ

Q: How do I convert a temporary image link to a permanent one?

A: You cannot directly convert a temporary link to a permanent one. Instead, download the image through a backend service and then upload it to OSS, to generate a new permanent link.

Example code: Download an image to your local machine

import requests

def download_and_save_image(image_url, save_path):
    try:
        response = requests.get(image_url, stream=True, timeout=300) # Set a timeout.
        response.raise_for_status() # Raise an exception if the HTTP status code is not 200.
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"Image successfully downloaded to: {save_path}")
        # You can add the logic to upload to permanent storage here.
    except requests.exceptions.RequestException as e:
        print(f"Image download failed: {e}")

if __name__ == '__main__':
    image_url = "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx?Expires=xxx"
    save_path = "image-translation.jpg"
    download_and_save_image(image_url, save_path)

Q: How do I view my model usage?

A: One hour after a model invocation is complete, you can view metrics such as the call count and success rate on the Model Observation page. For more information, see How do I view model call records?

Model overview

Examples

Model and pricing

HTTP

Step 1: Create a task and get a task ID

Request parameters

Image translation

Request headers

Request body

Response parameters

Successful response

Error response

Step 2: Query the result using the task ID

Request parameters

Query task result

Request headers

URL path parameters

Response parameters

Task successful

Task failed

Supported languages

Configure access permission

Error codes

FAQ