Call Qwen-MT-Image Translation API for Async Image Localization - Alibaba Cloud Model Studio

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

Get 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 Use Postman or cURL.

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. Must be `application/json`.
Authorization `string` (Required) The authentication credentials using a Model Studio API key. Example: `Bearer sk-xxxx`
X-DashScope-Async `string` (Required) Enables asynchronous processing. Must be `enable` as HTTP requests support only asynchronous processing. Important Returns "current user api does not support synchronous calls" error if not included.
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. 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 to resolve the issue. `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` Task output information. Properties task_id `string` The ID of the task. Can be used to query the task for up to 24 hours. task_status `string` The status of the task. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task does not exist or status is unknown
request_id `string` Unique identifier for the request. Use for tracing and troubleshooting issues.
message `string` Detailed error message. Returned only when the request fails. See error codes for details.
code `string` The error code. Returned only when the request fails. See error codes for details.

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

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 set to FAILED with an error code and message. See error codes 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 ID of the task. Can be used to query the task for up to 24 hours. task_status `string` The status of the task. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task does not exist or status is unknown submit_time `string` The time when the task was submitted. Time is in UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. scheduled_time `string` The time when the task started running. Time is in UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. end_time `string` The time when the task was completed. Time is in UTC+8. 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` The error code. Returned only when the request fails. See error codes for details. 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 identifier for the request. Use for tracing and troubleshooting issues.

Supported languages

Either the source or target language 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 detection if unsure.

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: Charged per successfully generated image. Failed calls or errors incur no fees.
If an image contains no translatable text (or no text in non-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 the content in the image not translated?

The entity segmentation feature excludes text on image entities (people, products, logos) from translation. To translate all text, set ext.config.imgSegment to false.

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

You cannot directly convert temporary links to permanent ones. Download the image via a backend service and upload to OSS for 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 (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.

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