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

Qwen-MT-Image accurately translates text in images while preserving 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 Mainland China deployment mode. You must use a corresponding API key.

Model overview

Source language: English

Japanese

Portuguese

Arabic

Model

Description

Output image specifications

qwen-mt-image

Qwen - image translation model

Supports translation between Chinese or English and other languages. It does not support direct translation between non-Chinese or non-English languages, such as from Japanese to Korean. See Supported languages.

Image format: JPG.

Prerequisites

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

HTTP

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

The HTTP API uses an asynchronous mode. The call involves two steps:

Create a task and obtain a task ID: Send a request to create a task. The request returns a task ID (task_id).
Query the 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. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, poll to retrieve the result.
For a tutorial, see Postman.

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", "ext": { "config": { "imageSegment": false } } } }'`
Request headers
Content-Type `string` (Required) The content type of the request. You must set this parameter to `application/json`.
Authorization `string` (Required) The authentication credentials. This API uses a Model Studio API key for authentication. For example, `Bearer sk-xxxx`.
X-DashScope-Async `string` (Required) This parameter is used to configure asynchronous processing. Because HTTP requests support only asynchronous processing, you must set this parameter to `enable`. Important If you do not include this request header, the error message "current user api does not support synchronous calls" is returned.
Request body
model `string` (Required) The name of the model. Set this to `qwen-mt-image`.
input `object` (Required) The input parameter object, which contains the following fields: Properties image_url `string` (Required) A publicly accessible URL of the image. HTTP and HTTPS protocols are supported. Format: JPG, JPEG, PNG, BMP, PNM, PPM, TIFF, or WEBP Dimensions: 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: No more than 100 MB The URL cannot contain Chinese characters. 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) The 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 adapt the translation style 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) Provides terminology intervention. This feature lets you set specific translations for terms to meet the requirements of a particular 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 Programming Interface", "tgt": "API"}, {"src": "Machine Learning", "tgt": "ML"}] config `object` (Optional) Properties imageSegment `bool` (Optional) Specifies whether to enable image subject segmentation. When enabled, the model does not translate text on subjects in the image, such as people, products, or logos. `false` (default): Translates all text in the image. `true`: Does not translate text on image subjects. Note: The parameter was previously named `skipImgSegment` (specifies whether to skip image subject segmentation). For backward compatibility, this parameter is still supported. However, we recommend the new `imageSegment` parameter.

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": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` Information about the task output. Properties task_id `string` The task ID. You can use this ID to query the task for up to 24 hours. task_status `string` The task status. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: The task does not exist or its status is unknown.
request_id `string` The unique request ID. You can use this ID to trace and troubleshoot issues.
message `string` A detailed error message. This parameter is returned only when the request fails. For more information, see Error messages.
code `string` The error code. This parameter is returned only when the request fails. 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 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 authentication credentials. This API uses a Model Studio API key for authentication. For example, `Bearer sk-xxxx`.
URL path parameters
task_id `string` (Required) The task ID.

Response parameters	Task successful - translatable content exists Task data, such as the task status and image URLs, is retained for only 24 hours and is then automatically purged. 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 successful - no translatable content If the image contains no translatable text (for example, if no text remains after subject identification), the task still succeeds and is billed normally. However, the message `No text detected for translation` is returned. `{ "request_id": "0ccb84aa-e034-431d-9d54-08e14fxxxxxx", "output": { "task_id": "34ec4208-97d6-498b-a390-9173f7xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2026-01-12 17:56:23.625", "scheduled_time": "2026-01-12 17:56:23.656", "end_time": "2026-01-12 17:56:25.324", "image_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.jpg?Expires=xxx", "message": "No text detected for translation" }, "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` Information about the task output. Properties task_id `string` The task ID. You can use this ID to query the task for up to 24 hours. task_status `string` The task status. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: The task does not exist or its status is unknown. submit_time `string` The time when the task was submitted. The time is in UTC+8. The format is `YYYY-MM-DD HH:mm:ss.SSS`. scheduled_time `string` The time when the task started running. The time is in UTC+8. The format is `YYYY-MM-DD HH:mm:ss.SSS`. end_time `string` The time when the task was completed. The time is in UTC+8. 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. This parameter is returned only when the request fails. For more information, see Error messages. message `string` 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 segmentation. In this case, the task still succeeds and is billed normally, 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, the source or target language 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
German	de	Supported	Not supported
Vietnamese	vi	Supported	Supported
Malay	ms	Not supported	Supported
Thai	th	Not supported	Supported
Indonesian	id	Not supported	Supported
Arabic	ar	Not supported	Supported

Billing and rate limits

For free quota and pricing, see Model pricing.
For rate limits, see Rate limits.
Billing: You are billed based on the number of successfully generated images. Failed model calls or processing errors do not incur any fees.
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 is still considered successful and is billed as normal. In this case, the API returns the message No text detected for translation.

Configure image access permissions

Images are stored in Object Storage Service (OSS). The links provide public access but 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: Why is the content in the image not translated?

A: The entity segmentation feature prevents the model from translating text on entities in the image, such as people, products, or logos. To translate all the text, set the ext.config.imgSegment parameter to false.

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 call is complete, you can go to the Model Observation page to view metrics such as the call count and success rate. How do I view model call records?

Model overview

Prerequisites

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 - translatable content exists

Task successful - no translatable content

Task failed

Supported languages

Billing and rate limits

Configure image access permissions

Error codes

FAQ