Qwen-MT-Image API reference

Qwen-MT-Image accurately translates text in images while preserving the original layout. The model also supports domain hints, sensitive word filtering, and terminology intervention. Important

This document applies only to the Chinese Mainland deployment mode. Use the 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. Direct translation between two non-Chinese, non-English languages (e.g., Japanese to Korean) is not supported. See Supported languages .	Image format: JPG

Prerequisites

Create 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

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 <i>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).

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 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. ** <b>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.

json

{
 "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 messages.

json

{
 "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 messages.

code *string* Error code. Returned only for failed requests. 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. Nonexistent or expired IDs return status UNKNOWN.
The url for successful tasks is valid for 24 hours. Download and save promptly.

Request parameters

## Query task result

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

curl

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.

json

{
 "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.

json

{
 "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 messages.

json

{
 "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. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time *string* The time when the task was executed. The time is in UTC+8 and 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 and the 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 messages.

**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. Propertiesimage_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 Rate limits.
Billing is per successfully generated image. Failed calls and errors incur no fees .
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 messages 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

HELPCODEESCAPE-python
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 (Singapore) or Monitoring (China (Beijing)) 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.

Qwen-MT-Image API reference ​

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 ​

Error codes ​

FAQ ​

Q: Why is content in the image not translated? ​

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

Q: How do I view model invocation metrics? ​

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

Qwen-MT-Image API reference

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

Error codes

FAQ

Q: Why is content in the image not translated?

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

Q: How do I view model invocation metrics?

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