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

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.

Model overview

Source language: English	Japanese
Portuguese	Arabic

Source language: English

Japanese

Portuguese

Arabic

Model	Description	Available regions	Output image specifications
qwen-mt-image-2.0	An image translation model that translates text in images across 55 languages while accurately preserving original layout and content. Supports terminology definitions, sensitive word filtering, and product subject detection. Provides flexible, accurate, and efficient image localization services.	China (Beijing) Singapore	Image format: JPG
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.	China (Beijing)	Image format: JPG

Model

Description

Available regions

Output image specifications

qwen-mt-image-2.0

An image translation model that translates text in images across 55 languages while accurately preserving original layout and content.

Supports terminology definitions, sensitive word filtering, and product subject detection. Provides flexible, accurate, and efficient image localization services.

China (Beijing)

Singapore

Image format: JPG

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.

China (Beijing)

Image format: JPG

Prerequisites

Obtain an API key and export the API key as an environment variable.

Synchronous call

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis. Replace {WorkspaceId} with your actual Workspace ID.

In synchronous mode, the request waits for processing to complete and returns the translated image URL directly, without polling task status.

Request parameters

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.

Request body

model string (Required)

Model name. Set to qwen-mt-image-2.0 or 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. qwen-mt-image-2.0 has no language restrictions; qwen-mt-image requires at least one of the source or target languages to 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. qwen-mt-image-2.0 has no language restrictions; qwen-mt-image requires at least one of the source or target languages to 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).

ImportantDomain 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.

tgtstring (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

imageSegmentbool (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.

curl

# The URL below is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen-mt-image-2.0",
    "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"
    }
}'

Python

import requests
import os

# Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis"

headers = {
  "Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}",
  "Content-Type": "application/json"
}

# Synchronous call: do not set X-DashScope-Async header
payload = {
  "model": "qwen-mt-image-2.0",
  "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"
  }
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result)
# Synchronous mode returns image_url directly
image_url = result["output"]["image_url"]
print(f"Translation complete, image URL: {image_url}")

Response parameters

output object

Output information.

Properties

image_url string

URL of the generated image (same dimensions as source, JPG format). Valid for 24 hours. Download and save promptly.

usage object

Usage statistics. Counted only for successful results.

Properties

image_count integer

Number of images generated (always 1).

request_id string

Unique request identifier for tracing and troubleshooting.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

Successful response

{
    "output": {
        "image_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.jpg?Expires=xxx"
    },
    "usage": {
        "image_count": 1
    },
    "request_id": "b60d747a-adee-940a-aa3e-ac55b957189a"
}

Error response

See Error codes.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Asynchronous call

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis. Replace {WorkspaceId} with your actual Workspace ID.

The asynchronous call has 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

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. Must be enable.

ImportantWithout this header, synchronous mode is used (only qwen-mt-image-2.0 supports synchronous calls). The qwen-mt-image model must include this header.

Request body

model string (Required)

Model name. Set to qwen-mt-image-2.0 or 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. qwen-mt-image-2.0 has no language restrictions; qwen-mt-image requires at least one of the source or target languages to 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. qwen-mt-image-2.0 has no language restrictions; qwen-mt-image requires at least one of the source or target languages to 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).

ImportantDomain hints currently support only English.

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.

tgtstring (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

imageSegmentbool (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.

curl

# The URL below is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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-2.0",
    "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
            }
        }
    }
}'

Python

import requests
import os

# Replace {WorkspaceId} with your actual workspace ID
url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis"

headers = {
  "X-DashScope-Async": "enable",
  "Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}",
  "Content-Type": "application/json"
}

payload = {
  "model": "qwen-mt-image-2.0",
  "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
      }
    }
  }
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result)
# Save task_id for Step 2
task_id = result["output"]["task_id"]

Response parameters

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.

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"
}

Step 2: Query the result using the task ID

GET https://{WorkspaceId}.ap-southeast-1.maas.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

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.

Query task result

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

# The URL below is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobject

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: YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task was executed. Format: YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. Format: 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.

messagestring

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.

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"
    }
}

Supported languages

Set source_lang to auto for automatic language detection.

Languages supported by qwen-mt-image-2.0

qwen-mt-image-2.0 supports translation between any combination of the 55 languages listed below, without requiring Chinese or English as source or target. All languages can be used as both source and target.

Language	Code
Simplified Chinese	zh
Traditional Chinese	zh-tw
English	en
Japanese	ja
Korean	ko
German	de
Spanish	es
Russian	ru
French	fr
Portuguese	pt
Italian	it
Vietnamese	vi
Indonesian	id
Malay	ms
Thai	th
Arabic	ar
Dutch	nl
Polish	pl
Turkish	tr
Ukrainian	uk
Greek	el
Hungarian	hu
Romanian	ro
Czech	cs
Swedish	sv
Danish	da
Finnish	fi
Norwegian	no
Hindi	hi
Tamil	ta
Telugu	te
Nepali	ne
Persian	fa
Azerbaijani	az
Kazakh	kk
Uzbek	uz
Mongolian	mn
Uyghur	ug
Belarusian	be
Bulgarian	bg
Serbian	sr
Croatian	hr
Bosnian	bs
Slovenian	sl
Slovak	sk
Macedonian	mk
Latvian	lv
Lithuanian	lt
Irish	ga
Luxembourgish	lb
Afrikaans	af
Latin	la
Chechen	ce
Ingush	inh
Mari	chm

Languages supported by qwen-mt-image

qwen-mt-image requires at least one of the source or target languages to be Chinese or English. Direct translation between other language pairs (e.g., Japanese to Korean) is not supported.

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 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)
    response.raise_for_status()
    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}")
  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 Billing 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.