How to call the Qwen-MT-Image translation API-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Model overview

Source language: Chinese

English

Japanese

Korean

Spanish

French

Model	Description	Output image specifications
qwen-mt-image	Qwen image translation model. Supports translation between Chinese or English and other languages. Direct translation between two non-Chinese, non-English languages (e.g., Japanese to Korean) is not supported. See Supported languages.	Image format: JPG

Prerequisites

Obtain an API key and export 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 with 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: Poll the task status with the task_id until completion and retrieve the image URL.

Step 1: Create a task and get a task ID

Note

After creating a task, use the returned task_id to query the result. The task_id is valid for 24 hours. Poll for results instead of creating duplicate tasks.
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/ordhsk/1.webp", "source_lang": "zh", "target_lang": "en", "ext": { "config": { "imageSegment": false } } } }'`
Request headers
Content-Type `string` (Required) The content type of the request. Must be `application/json`.
Authorization `string` (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
X-DashScope-Async `string` (Required) Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be `enable`. Important If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request body
model `string` (Required) Model name. Set to `qwen-mt-image`.
input `object` (Required) An input parameter object containing the following fields: Properties image_url `string` (Required) Publicly accessible image URL (HTTP or HTTPS). To obtain a public URL for a local file, see Upload a file to obtain a temporary URL. 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/ordhsk/1.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 translation style for a specific domain. Use English to describe the scenario, style, and requirements (max 200 words for quality). 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) Sensitive words to filter from image text before translation. The filter performs an exact match (case-sensitive). Sensitive words can be in any supported source or target language (max 50 per request for quality). Example: ["10% off entire store", "7-day no-questions-asked return"] terminologies `array` (Optional) Use terminology intervention to set specific translations for domain-specific terms. Term pair languages must match `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) When enabled, image subject segmentation excludes text on image subjects (people, products, logos) from translation. `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 Task creation failed. See Error codes. `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` Task output information. Properties task_id `string` The task ID. Valid for queries for 24 hours. task_status `string` The status of the task. Enumeration values PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: The task does not exist or its status is unknown.
request_id `string` Unique request identifier for tracing and troubleshooting.
message `string` Detailed error message. Returned only for failed requests. See Error codes.
code `string` Error code. Returned only for failed requests. See Error codes.

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. Nonexistent or expired IDs return status UNKNOWN.
The url for successful tasks is valid for 24 hours. Download and save promptly.
The default RPS for this query API is 1. For more frequent queries or event notifications, configure an asynchronous task callback.
To query or cancel tasks in batches, see Manage asynchronous tasks.

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) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
URL path parameters
task_id `string` (Required) The ID of the task.

Response parameters	Task successful - translatable content exists Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save 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 (e.g., after subject segmentation), the task still succeeds and is billed normally, but returns `No text detected for translation`. `{ "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 When a task fails, `task_status` is FAILED with an error code and message. See Error codes. `{ "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. Valid for queries for 24 hours. task_status `string` The status of the task. Enumeration values 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. format is YYYY-MM-DD HH:mm:ss.SSS. scheduled_time `string` The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS. end_time `string` The time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS. image_url `string` The URL of the model-generated image (same dimensions as the source, JPG format, valid for 24 hours). Download and save promptly. code `string` Error code. Returned only for failed requests. See Error codes. message `string` Detailed information about the request failure. For more information, see Error messages. Usually not returned for successful requests. Returned only when the image contains no translatable text (e.g., after subject segmentation). The task still succeeds and is billed normally, returning `No text detected for translation`.
usage `object` Usage statistics. These are counted only for successful tasks. Properties image_count `integer` Number of images generated (always 1).
request_id `string` Unique request identifier for tracing and troubleshooting.

Supported languages

At least one of the source or target languages must be Chinese or English. Direct translation between other language pairs (e.g., Japanese to Korean) is not supported. Set source_lang to auto for automatic language 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 Qwen-Image.
Billing is per successfully generated image. Failed calls and errors incur no fees or consume no free quota.
If an image contains no translatable text (or no text outside subject areas after segmentation), the task still succeeds and is billed normally, returning No text detected for translation.

Error codes

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

FAQ

Q: Why is content in the image not translated?

The subject segmentation feature excludes text on image subjects (people, products, logos) from translation. To translate all text in the image, set ext.config.imageSegment to false.

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

Temporary links cannot be converted directly to permanent ones. Download the image via a backend service and upload it to OSS to get a 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 model invocation metrics?

A: One hour after a model invocation completes, go to the Monitoring (China (Beijing)) or Monitoring (Singapore) page to view metrics such as invocation count and success rate. For more information, see Bill query and cost management.

Q: How do I get the domain name whitelist for image storage?

A: Images generated by models are stored in OSS. The API returns a temporary public URL. To configure a firewall whitelist for this download URL, note the following: The underlying storage may change dynamically. This topic does not provide a fixed OSS domain name whitelist to prevent access issues caused by outdated information. If you have security control requirements, contact your account manager to obtain the latest OSS domain name list.

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