Qwen画像生成・編集3.0モデルは、テキストから画像への変換(T2I)と画像から画像への変換/画像編集(I2I)の両方をサポートしています。テキストプロンプトから直接画像を生成したり、1-3枚の参照画像と編集指示を組み合わせて画像を編集したりできます。OpenAI互換プロトコルとDashScopeプロトコルの両方をサポートしています。
モデル概要
モデル | 説明 | 出力画像の仕様 |
|---|---|---|
qwen-image-3.0-pro | テキストから画像への変換(T2I)と画像から画像への変換/画像編集(I2I)の両方をサポートするQwen画像生成・編集3.0モデルです。 | 画像解像度:
画像形式:PNG |
qwen-image-3.0 | テキストから画像への変換(T2I)と画像から画像への変換/画像編集(I2I)の両方をサポートするQwen画像生成・編集3.0標準モデルです。品質と速度のバランスが取れています。 |
可用性
モデル、エンドポイント URL、および API キーは同じリージョンに属している必要があります。クロスリージョン呼び出しは失敗します。
- モデルを選択する:ターゲットリージョンでモデルが利用可能であることを確認してください。
- URLの選択:モデルのリージョンに一致するエンドポイントURLを選択してください。HTTPおよびDashScope SDKのURLの両方がサポートされています。
- APIキーの設定:対象リージョンのAPIキーを取得し、APIキーを環境変数として設定してください。
- SDKのインストール:SDKでAPI呼び出しを行うには、DashScope SDKをインストールしてください。
注記本トピックのサンプルコードは シンガポール リージョンに適用されます。
重要Alibaba Cloud Model Studioは、中国(北京)およびシンガポールリージョン向けにワークスペース固有のドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しいドメインへの移行を推奨します。
- 中国(北京):
https://dashscope.aliyuncs.comからhttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.comへ - シンガポール:
https://dashscope-intl.aliyuncs.comからhttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.comへ
{WorkspaceId}はワークスペースIDであり、Alibaba Cloud Model StudioコンソールのWorkspace Detailsページで確認できます。既存のドメインは引き続き完全に機能します。
アクセス方法
Qwen画像生成・編集3.0は、同一のモデル機能を持つ3つのアクセス方法を提供しています。アプリケーションに適したものを選択してください。
アクセス方法 | 使用場面 |
|---|---|
すでにOpenAI ImagesプロトコルまたはOpenAI SDK上に構築されたアプリケーション向けです。 | |
推奨されます。パブリック URL と Base64 画像入力の両方を含む、完全な機能カバレッジを提供します。 | |
バッチ生成、または接続を開いたままにwantない場合に使用します。タスクを送信し、 |
OpenAI 互換
アプリケーションがすでにOpenAI ImagesプロトコルまたはOpenAI SDK上に構築されている場合、リクエスト構造を変更することなく、OpenAI互換モードを通じてQwen画像生成・編集3.0を呼び出すことができます。テキストから画像(T2I)と画像から画像/画像編集(I2I)は同じエンドポイントを共有します:T2Iの場合はomit image とし、I2Iの場合は image を指定します。
注記OpenAI互換モードは同期・非ストリーミングエンドポイントです。画像編集では、/images/generations上のimage拡張フィールドを使用します。公式OpenAIの/images/editsエンドポイントで使用されるマルチパートファイルアップロード形式は使用しません。現在、以下はまだサポートされていません:非同期呼び出し、ストリーミング出力、部分画像、/images/edits、マルチパート、およびマスク。response_format=b64_jsonを渡してもエラーにはなりませんが、無視され、レスポンスには引き続き画像URLが含まれます。非同期呼び出しを行うには、DashScope非同期を使用してください。
URL
Singapore
HTTP エンドポイント:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK 呼び出し用の base_url:https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
米国(バージニア)
HTTP エンドポイント:POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK 呼び出し用の base_url:https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
中国(北京)
HTTP エンドポイント:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK 呼び出し用の base_url:https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
China (Hong Kong)
HTTP エンドポイント:POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK 呼び出し用の base_url:https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
Germany (Frankfurt)
HTTP エンドポイント:POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK 呼び出し用の base_url:https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
Japan (Tokyo)
HTTP エンドポイント:POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK 呼び出し用の base_url:https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
{WorkspaceId}を実際のワークスペースIDに置き換えます。
リクエストパラメーターヘッダーContent-Type リクエストのコンテンツタイプです。 Authorization Model Studio APIキーを使用してリクエストを認証します。例:Bearer sk-xxxx。 リクエストボディDashScopeプロトコルとは異なり、OpenAI互換モードではすべてのパラメータがリクエストボディのトップレベルに配置されます。 model モデル名です。利用可能な値: prompt 生成または編集wantたい画像の内容、スタイル、構図を記述するポジティブプロンプトです。中国語と英語の両方がサポートされています。推奨最大値:4,500トークン。空文字列にすることはできません。 image 入力画像のURLまたはBase64エンコードデータです。テキストから画像への変換(T2I)の場合はこのパラメータを省略してください。画像から画像への変換(I2I)の場合は指定する必要があり、1-3枚の画像がサポートされています。単一画像の場合は文字列を渡し、複数画像の場合は文字列の配列を渡してください。複数の画像が提供される場合、順序は配列のシーケンスによって定義されます。 注意:
n 出力画像の数です。値の範囲:1~6。デフォルト:1。整数である必要があります。 size 出力画像の解像度を 警告OpenAIプロトコルでは、DashScopeプロトコルで使用されるアスタリスク
negative_prompt 画像にwantとしない内容を記述するネガティブプロンプトです。 seed ランダムシードです。値の範囲: prompt_extend インテリジェントプロンプト書き換えを有効にするかどうかです。デフォルト: prompt_extend_mode プロンプトの書き換え方法です。デフォルト:
enable_thinking 思考モードを有効にします。デフォルトは watermark ウォーターマークを追加するかどうか。デフォルト: 注記 | |
レスポンスパラメーターcreated レスポンスが作成された際の Unix タイムスタンプ(秒単位)です。 data 生成結果のリストです。 usage この呼び出しのリソース使用量です。成功時のみ返されます。これらは画像の入出力メータリングフィールドであり、トークン使用量ではありません。 error エラーの詳細です。失敗したリクエストに対してのみ返されます。 注記DashScopeプロトコルとは異なり、OpenAI互換モードではレスポンスボディにrequest_idが返されません | Success画像 URL は 24 時間のみ保持され、その後自動的に削除されます。生成された画像は速やかに保存してください。 エラーリクエストが失敗した場合、レスポンスには |
SDK
まずOpenAI Python SDKをインストールまたはアップグレードしてください。
pip install -U openai
重要画像生成には時間がかかる場合があります。明示的で十分なクライアントタイムアウトを設定してください。複数画像出力(nが大きい場合)や同時リクエストの場合は、クライアントが早期に切断されないよう600秒から開始してください。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads 'Il Messaggero' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street's end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere.",
size="1024x1024",
n=1,
# All parameters above are official OpenAI parameters. Extension fields such as
# image and prompt_extend go through extra_body. See the I2I example.
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.",
size="1024x1024",
n=1,
extra_body={
# A single image can also be passed as a plain string. Base64 is also accepted:
# data:{MIME_type};base64,{base64_data}
"image": [
"https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
],
"prompt_extend": True,
},
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
import os
from openai import OpenAI, APIStatusError
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
try:
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="A vertical outdoor portrait photograph with a warm afternoon street atmosphere.",
)
print(response.data[0].url)
except APIStatusError as exc:
print(f"status_code: {exc.status_code}")
print(f"request_id: {exc.request_id}")
print(exc)
DashScope 同期 API(推奨)
HTTP
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
米国(バージニア)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
中国(北京)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
China (Hong Kong)
POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Germany (Frankfurt)
POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Japan (Tokyo)
POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
{WorkspaceId}を実際のワークスペースIDに置き換えます。
リクエストパラメーターヘッダーContent-Type リクエストのコンテンツタイプです。 Authorization Model Studio APIキーを使用してリクエストを認証します。例:Bearer sk-xxxx。 リクエストボディmodel モデル名です。利用可能な値: input 入力パラメーターオブジェクトで、以下のフィールドが含まれます。 parameters 画像生成を制御するための追加パラメーターです。 | |
レスポンスパラメーターoutput モデルの生成結果が含まれます。 usage この呼び出しのリソース使用量です。成功時のみ返されます。これらは画像の入出力メータリングフィールドであり、トークン使用量ではありません。 request_id トレースおよびトラブルシューティングのための一意のリクエスト識別子です。 code エラーコードです。失敗したリクエストに対してのみ返されます。エラーコードをご確認ください。 message 詳細なエラーメッセージです。失敗したリクエストに対してのみ返されます。エラーコードをご確認ください。 | Successタスクデータ(タスクステータスおよび画像URL)は24時間のみ保持され、その後自動的に削除されます。生成された画像は速やかに保存してください。 エラータスクが失敗した場合、レスポンスにはエラーコードとメッセージが含まれます。トラブルシューティングについては、エラーコードを参照してください。 |
SDK
以下の例では、PythonおよびJava SDKを使用して画像から画像への変換/画像編集(I2I)を行うAPIの呼び出し方法を示します。
import os
import base64
import mimetypes
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
return f"data:{mime_type};base64,{encoded_string}"
# [Method 1] Use a public image URL
image_url = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
# [Method 2] Use a Base64-encoded image
# image_url = encode_file("./your_image.png")
response = MultiModalConversation.call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen-image-3.0-pro",
messages=[{
"role": "user",
"content": [
{"image": image_url},
{"text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop."}
]
}],
prompt_extend=True
)
print(response)
if response.status_code == 200:
url = response.output.choices[0].message.content[0]["image"]
print(f"Generated image URL: {url}")
else:
print(f"Error: {response.code} - {response.message}")
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;
public class ImageEditExample {
public static void main(String[] args) {
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
// [Method 1] Use a public image URL
String imageUrl = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png";
// [Method 2] Use a Base64-encoded image
// String imageUrl = encodeFile("/path/to/your/image.png");
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("image", imageUrl),
Collections.singletonMap("text", "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.")
))
.build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen-image-3.0-pro")
.messages(Arrays.asList(userMessage))
.parameter("prompt_extend", true)
.build();
try {
MultiModalConversationResult result = conv.call(param);
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
}
public static String encodeFile(String filePath) {
Path path = Paths.get(filePath);
if (!Files.exists(path)) {
throw new IllegalArgumentException("File does not exist: " + filePath);
}
String mimeType = null;
try {
mimeType = Files.probeContentType(path);
} catch (IOException e) {
throw new IllegalArgumentException("Cannot detect file type: " + filePath);
}
if (mimeType == null || !mimeType.startsWith("image/")) {
throw new IllegalArgumentException("Unsupported or unrecognized image format");
}
byte[] fileBytes = null;
try {
fileBytes = Files.readAllBytes(path);
} catch (IOException e) {
throw new IllegalArgumentException("Cannot read file content: " + filePath);
}
String encodedString = Base64.getEncoder().encodeToString(fileBytes);
return "data:" + mimeType + ";base64," + encodedString;
}
}
DashScope 非同期 API
上記の同期呼び出しに加えて、Qwen画像生成・編集3.0は非同期呼び出しもサポートしています。非同期APIは同期APIと同じリクエストパラメータ構造を共有します。X-DashScope-Async: enableヘッダーを追加するだけで済みます。サービスがリクエストを受理した後、タスクID(task_id)を返しますので、それを使用して最終結果をクエリAPIにポーリングします。
重要非同期APIのエンドポイントは同期APIとは異なります。同期エンドポイントの代わりに、このセクションのエンドポイントを使用してください。
HTTP
非同期呼び出しでは、2段階のワークフローを使用します。
- タスクを作成してタスクIDを取得する:タスク作成のリクエストを送信します。レスポンスにはタスクID(task_id)が含まれます。
- タスクIDを使用して結果をポーリングする:task_idを使用して、タスクが完了し画像URLが返されるまでタスクステータスをポーリングします。
ステップ1:タスクを作成してタスクIDを取得する
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
米国(バージニア)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
中国(北京)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
China (Hong Kong)
POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Germany (Frankfurt)
POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Japan (Tokyo)
POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
リクエストパラメーターヘッダーContent-Type リクエストのコンテンツタイプです。 Authorization Model Studio APIキーを使用してリクエストを認証します。例:Bearer sk-xxxx。 X-DashScope-Async 非同期処理を有効にします。値は 重要このリクエストヘッダーがない場合、「current user api does not support synchronous calls」というエラーが返されます。 リクエストボディmodel モデル名です。利用可能な値: input 入力パラメーターオブジェクトで、以下のフィールドが含まれます。 parameters 画像生成を制御するための追加パラメーターです。 | |
レスポンスパラメーターoutput タスクの受付情報です。 request_id トレースおよびトラブルシューティングのための一意のリクエスト識別子です。 code エラーコードです。失敗したリクエストに対してのみ返されます。エラーコードをご確認ください。 | 成功レスポンスタスクのステータスと結果を照会するには、 エラーレスポンスタスクの作成に失敗しました。エラーコードをご確認ください。 |
ステップ2:タスクIDを使用して結果をポーリングする
Singapore
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
米国(バージニア)
GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
中国(北京)
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
China (Hong Kong)
GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}
Germany (Frankfurt)
GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Japan (Tokyo)
GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
タスクを作成したときと同じリージョン、ワークスペース、およびAPIキーを使用する必要があります。クロスリージョンまたはクロスワークスペースのクエリはサポートされていません。
リクエストパラメーターヘッダーAuthorization Model Studio APIキーを使用してリクエストを認証します。例:Bearer sk-xxxx。 URL パスパラメーターtask_id タスクのID。 | タスク結果のクエリ
|
レスポンスパラメーターoutput タスクの出力情報です。 usage この呼び出しのリソース使用量です。成功時のみ返されます。これらは画像の入出力メータリングフィールドであり、トークン使用量ではありません。 request_id トレースおよびトラブルシューティングのための一意のリクエスト識別子です。 code エラーコードです。失敗したリクエストに対してのみ返されます。エラーコードをご確認ください。 message 詳細なエラーメッセージです。失敗したリクエストに対してのみ返されます。エラーコードをご確認ください。 | タスク成功タスクデータ(タスクステータスおよび画像URL)は24時間のみ保持され、その後自動的に削除されます。生成された画像は速やかに保存してください。 タスク失敗タスクが失敗した場合、 |
エラーコード
モデルの呼び出しに失敗してエラーメッセージが返された場合は、解決策としてエラーコードをご確認ください。