All Products
Search

This Product

    Alibaba Cloud Model Studio:Qwen-MT API reference

    Document Center

    Alibaba Cloud Model Studio:Qwen-MT API reference

    Last Updated:Feb 05, 2026

    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

    en

    Source language: English

    ja

    Japanese

    es

    Portuguese

    ar

    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:

    1. Create a task and obtain a task ID: Send a request to create a task. The request returns a task ID (task_id).

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

    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

    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

    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

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

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

    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

    Unique identifier for the request. Use for tracing and troubleshooting 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 Monitoring page to view metrics such as the call count and success rate. How to view model call records?