Cara memanggil API terjemahan gambar Qwen-MT-Image - Alibaba Cloud Model Studio

Qwen-MT-Image menerjemahkan teks dalam gambar secara akurat sekaligus mempertahankan tata letak aslinya. Model ini juga mendukung petunjuk bidang subjek (domain hint), penyaringan kata sensitif, dan intervensi terminologi.

PentingFitur yang dijelaskan dalam dokumen ini hanya tersedia di Wilayah China (Beijing). Anda harus menggunakan Kunci API untuk wilayah ini.

PentingAlibaba Cloud Model Studio telah merilis domain khusus berbasis ruang kerja untuk Wilayah China (Beijing): https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami menyarankan migrasi dari https://dashscope.aliyuncs.com ke domain baru tersebut.

{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan pada halaman Workspace Details di Konsol Alibaba Cloud Model Studio. Domain yang ada tetap berfungsi sepenuhnya.

Ikhtisar model

Bahasa sumber: English	Japanese
Portuguese	Arabic

Bahasa sumber: English

Japanese

Portuguese

Arabic

Model	Deskripsi	Spesifikasi gambar output
qwen-mt-image	Model terjemahan gambar Qwen. Mendukung terjemahan antara bahasa Chinese atau English dengan bahasa lainnya. Terjemahan langsung antara dua bahasa non-Chinese dan non-English (misalnya Japanese ke Korean) tidak didukung. Lihat Bahasa yang didukung.	Format gambar: JPG

Prasyarat

Dapatkan Kunci API dan ekspor Kunci API sebagai Variabel lingkungan.

HTTP

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis. Ganti {WorkspaceId} dengan ID Ruang Kerja aktual Anda.

API HTTP menggunakan mode asinkron dengan dua langkah:

Buat tugas dan dapatkan ID tugas: Kirim permintaan untuk membuat tugas. Respons permintaan mengembalikan ID tugas (task_id).
Kueri hasil menggunakan ID tugas: Lakukan polling status tugas dengan task_id hingga selesai dan ambil URL gambarnya.

Langkah 1: Buat tugas dan dapatkan ID tugas

Catatan

Setelah membuat tugas, gunakan task_id yang dikembalikan untuk mengkueri hasilnya. task_id berlaku selama 24 jam. Lakukan polling untuk hasil alih-alih membuat tugas duplikat.
Untuk tutorial, lihat Postman.

Parameter permintaan

Header permintaan

Content-Type string (Wajib)

Tipe konten permintaan. Harus berupa application/json.

Authorization string (Wajib)

Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

X-DashScope-Async string (Wajib)

Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus diatur ke enable.

PentingJika header permintaan ini tidak disertakan, akan dikembalikan error "current user api does not support synchronous calls".

Body permintaan

model string (Wajib)

Nama model. Atur ke qwen-mt-image.

input object (Wajib)

Objek parameter input yang berisi bidang-bidang berikut:

Properti

image_url string (Wajib)

URL gambar yang dapat diakses publik (HTTP atau HTTPS).

Format: JPG, JPEG, PNG, BMP, PNM, PPM, TIFF, atau WEBP
Dimensi: Lebar dan tinggi gambar harus antara 15 hingga 8.192 piksel. Rasio aspek harus antara 1:10 hingga 10:1.
Ukuran: Tidak lebih dari 100 MB
URL tidak boleh mengandung karakter Chinese.
Contoh: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250916/arpjoo/p1000391.webp

source_lang string (Wajib)

Bahasa sumber.

Nilai yang didukung: Nama lengkap bahasa, kode bahasa, atau auto (untuk deteksi otomatis). Nilai tidak peka huruf besar/kecil.
Batasan: Harus berbeda dari target_lang. Setidaknya salah satu dari bahasa sumber atau target harus berupa Chinese atau English.
Contoh: Chinese, en, atau auto

target_lang string (Wajib)

Bahasa target.

Nilai yang didukung: Nama lengkap bahasa atau kode bahasa. Nilai tidak peka huruf besar/kecil.
Batasan: Harus berbeda dari source_lang. Setidaknya salah satu dari bahasa sumber atau target harus berupa Chinese atau English.
Contoh: Chinese atau en

ext object (Opsional)

Bidang tambahan opsional.

Properti

domainHint string (Opsional)

Petunjuk bidang subjek untuk menyesuaikan gaya terjemahan sesuai bidang tertentu. Gunakan bahasa Inggris untuk menggambarkan skenario, gaya, dan persyaratan (maksimal 200 kata demi kualitas).

PentingPetunjuk bidang subjek saat ini hanya mendukung bahasa Inggris.

Contoh: Kalimat-kalimat berikut berasal dari percakapan antara penjual dan pembeli di platform e-commerce B2C. Terjemahkan kalimat tersebut ke dalam bahasa layanan pelanggan yang jelas dan menarik, serta pastikan terjemahannya sesuai untuk menangani potensi masalah atau sengketa.

sensitives array (Opsional)

Kata sensitif yang akan disaring dari teks gambar sebelum diterjemahkan. Penyaringan dilakukan dengan pencocokan eksak (peka huruf besar/kecil).

Kata sensitif dapat berupa bahasa sumber atau target yang didukung (maksimal 50 per permintaan demi kualitas).

Contoh: ["10% off entire store", "7-day no-questions-asked return"]

terminologies array (Opsional)

Gunakan intervensi terminologi untuk menetapkan terjemahan spesifik bagi istilah khusus bidang. Bahasa pasangan istilah harus sesuai dengan source_lang dan target_lang.

Properti

src string (Wajib)

Teks sumber istilah. Bahasanya harus sama dengan source_lang.

tgtstring (Wajib)

Teks target istilah. Bahasanya harus sama dengan target_lang.

Contoh: [{"src": "Application Programming Interface", "tgt": "API"}, {"src": "Machine Learning", "tgt": "ML"}]

config object (Opsional)

Properti

imageSegmentbool (Opsional)

Jika diaktifkan, segmentasi subjek gambar mengecualikan teks pada subjek gambar (orang, produk, logo) dari terjemahan.

false (default): Menerjemahkan semua teks dalam gambar.
true: Tidak menerjemahkan teks pada subjek gambar.

Catatan: Parameter ini sebelumnya bernama skipImgSegment (menentukan apakah akan melewati segmentasi subjek gambar). Untuk kompatibilitas mundur, parameter ini masih didukung. Namun, kami merekomendasikan penggunaan parameter baru imageSegment.

Terjemahan gambar

# URL berikut ini untuk Wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda berdasarkan wilayah.
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",
    "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
            }
        }
    }
}'

Parameter respons

output object

Informasi output tugas.

Properti

task_id string

ID tugas. Berlaku untuk kueri selama 24 jam.

task_status string

Status tugas.

Nilai enumerasi

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

request_id string

Identifikasi permintaan unik untuk pelacakan dan troubleshooting.

message string

Pesan error detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

Respons berhasil

Simpan task_id untuk mengkueri status dan hasil tugas.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Respons error

Pembuatan tugas gagal. Lihat Kode kesalahan.

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

Langkah 2: Kueri hasil menggunakan ID tugas

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Catatan

task_id berlaku selama 24 jam. ID yang tidak ada atau kedaluwarsa akan mengembalikan status UNKNOWN.
url untuk tugas yang berhasil berlaku selama 24 jam. Unduh dan simpan segera.

Parameter permintaan

Header permintaan

Authorization string (Wajib)

Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

Parameter path URL

task_id string (Wajib)

ID tugas.

Kueri hasil tugas

Ganti 86ecf553-d340-4e21-xxxxxxxxx dengan task_id aktual.

# URL di bawah ini untuk Wilayah China (Beijing). Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda berdasarkan wilayah.
curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter respons

outputobject

Informasi tentang output tugas.

Properti

task_id string

ID tugas. Berlaku untuk kueri selama 24 jam.

task_status string

Status tugas.

Nilai enumerasi

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

submit_time string

Waktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

Waktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

end_time string

Waktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.

image_url string

URL gambar yang dihasilkan model (dimensi sama dengan sumber, format JPG, berlaku selama 24 jam). Unduh dan simpan segera.

code string

Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

messagestring

Informasi detail tentang kegagalan permintaan. Untuk informasi lebih lanjut, lihat Pesan kesalahan.

Umumnya tidak dikembalikan untuk permintaan yang berhasil. Hanya dikembalikan ketika gambar tidak mengandung teks yang dapat diterjemahkan (misalnya setelah segmentasi subjek). Tugas tetap berhasil dan ditagih secara normal, mengembalikan No text detected for translation.

usage object

Statistik penggunaan. Hanya dihitung untuk tugas yang berhasil.

Properti

image_count integer

Jumlah gambar yang dihasilkan (selalu 1).

request_id string

Identifikasi permintaan unik untuk pelacakan dan troubleshooting.

Tugas berhasil - konten yang dapat diterjemahkan tersedia

Data tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam lalu secara otomatis dipurge. Segera simpan gambar yang dihasilkan.

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

Tugas berhasil - tidak ada konten yang dapat diterjemahkan

Jika gambar tidak mengandung teks yang dapat diterjemahkan (misalnya setelah segmentasi subjek), tugas tetap berhasil dan ditagih secara normal, tetapi mengembalikan 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
    }
}

Tugas gagal

Saat tugas gagal, task_status bernilai FAILED dengan kode dan pesan error. Lihat Kode kesalahan.

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

Bahasa yang didukung

Setidaknya salah satu dari bahasa sumber atau target harus berupa Chinese atau English. Terjemahan langsung antara pasangan bahasa lain (misalnya Japanese ke Korean) tidak didukung. Atur source_lang ke auto untuk deteksi bahasa otomatis.

Bahasa	Kode	Sebagai bahasa sumber	Sebagai bahasa target
Chinese	zh	Didukung	Didukung
English	en	Didukung	Didukung
Korean	ko	Didukung	Didukung
Japanese	ja	Didukung	Didukung
Russian	ru	Didukung	Didukung
Spanish	es	Didukung	Didukung
French	fr	Didukung	Didukung
Portuguese	pt	Didukung	Didukung
Italian	it	Didukung	Didukung
German	de	Didukung	Tidak didukung
Vietnamese	vi	Didukung	Didukung
Malay	ms	Tidak didukung	Didukung
Thai	th	Tidak didukung	Didukung
Indonesian	id	Tidak didukung	Didukung
Arabic	ar	Tidak didukung	Didukung

Penagihan dan batas laju

Untuk kuota gratis dan harga, lihat Harga model.
Untuk batas laju, lihat Batas laju.
Penagihan dilakukan per gambar yang berhasil dihasilkan. Panggilan gagal dan error tidak dikenai biaya .
Jika gambar tidak mengandung teks yang dapat diterjemahkan (atau tidak ada teks di luar area subjek setelah segmentasi), tugas tetap berhasil dan ditagih secara normal, mengembalikan No text detected for translation.

Kode kesalahan

Jika pemanggilan model gagal dan mengembalikan pesan error, lihat Kode kesalahan untuk penyelesaian.

FAQ

T: Mengapa konten dalam gambar tidak diterjemahkan?

Fitur segmentasi subjek mengecualikan teks pada subjek gambar (orang, produk, logo) dari terjemahan. Untuk menerjemahkan semua teks dalam gambar, atur ext.config.imageSegment ke false.

T: Bagaimana cara mengonversi tautan gambar sementara menjadi permanen?

Tautan sementara tidak dapat dikonversi langsung menjadi permanen. Unduh gambar melalui layanan backend dan unggah ke OSS untuk mendapatkan tautan permanen.

Kode contoh: Unduh gambar ke mesin lokal Anda

import requests

def download_and_save_image(image_url, save_path):
    try:
        response = requests.get(image_url, stream=True, timeout=300) # Tetapkan timeout.
        response.raise_for_status() # Bangkitkan exception jika kode status HTTP bukan 200.
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"Gambar berhasil diunduh ke: {save_path}")
        # Anda dapat menambahkan logika untuk mengunggah ke penyimpanan permanen di sini.
    except requests.exceptions.RequestException as e:
        print(f"Pengunduhan gambar gagal: {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)

T: Bagaimana cara melihat metrik pemanggilan model?

J: Satu jam setelah pemanggilan model selesai, buka halaman Monitoring (Singapura) atau Monitoring (China (Beijing)) untuk melihat metrik seperti jumlah pemanggilan dan tingkat keberhasilan. Untuk informasi lebih lanjut, lihat Penagihan dan manajemen biaya.

T: Bagaimana cara mendapatkan daftar putih nama domain untuk penyimpanan gambar?

J: Gambar yang dihasilkan oleh model disimpan di OSS. API mengembalikan URL publik sementara. Untuk mengonfigurasi daftar putih firewall untuk URL unduhan ini, perhatikan hal berikut: Penyimpanan dasar dapat berubah secara dinamis. Topik ini tidak menyediakan daftar putih nama domain OSS tetap untuk mencegah masalah akses akibat informasi yang kedaluwarsa. Jika Anda memiliki persyaratan kontrol keamanan, hubungi account manager Anda untuk mendapatkan daftar nama domain OSS terbaru.