すべてのプロダクト
Search
ドキュメントセンター

Alibaba Cloud Model Studio:Z-Image API リファレンス

最終更新日:Feb 28, 2026

Z-Image は、高速に画像を生成できる軽量なテキストから画像への変換モデルであり、中国語および英語のテキストレンダリングをサポートし、さまざまな解像度および縦横比に対応しています。

クイックアクセス:オンライン体験シンガポール | 中国 (北京) | 技術ブログ

サンプル画像

入力プロンプト

出力画像

短い黒髪のスタイリッシュな若い女性が、鮮やかな漫画風の壁画の壁の前で自信を持って立っている写真。全身黒の装い:ふわっとしたボンバージャケット(レースの襟付き)、カーゴショーツ、フィッシュネットタイツ、厚底の黒いドクマーテンズを履き、腰からゴールドチェーンが垂れています。背景には、カラフルなコミック風のパネルが4つあり、1つは「GRAND STAGE」と記載されており、スニーカーとゲータレードのボトルが描かれています。2つ目は、緑色のナイキスニーカーとピザのスライスが描かれています。3つ目は「HARAJUKU st」と記載されており、浮遊する靴が描かれています。4つ目は、スケートボードに乗った青いマウスが「Takeshita WELCOME.」というテキストとともに描かれています。主な明るい色は黄色、ターコイズ、オレンジ、ピンク、緑です。吹き出し、ハーフトーンパターン、遊び心のあるキャラクターが都会的なストリートアートの美学を高めています。日中の光が均等にシーンを照らしており、足元の地面は白いタイル張りの舗装です。全身ポートレート、中央構図、やや傾いた立ち姿、カメラとのアイコンタクト。高精細、シャープなフォーカス、ダイナミックなフレーミング。

b16c8008-83c1-4c80-ae22-786a2299bec3-1-转换自-png

モデル概要

モデル名

モデル説明

出力画像仕様

z-image-turbo

軽量モデルで、画像を高速に生成します

画像解像度:合計ピクセル数は 512×512 ~ 2048×2048 の範囲です。推奨解像度については、「size パラメーター設定」をご参照ください。

画像フォーマット:PNG

画像枚数:固定で 1 枚

説明

API を呼び出す前に、各リージョンでサポートされているモデル一覧をご確認ください。

前提条件

API キーを取得し、API キーを環境変数として設定します(今後非推奨となり、「API キーの設定」に統合されます)

同期 HTTP 呼び出し

シンガポールリージョンPOST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

中国 (北京) リージョンPOST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

リクエストパラメーター

テキストから画像への変換

この例では、画像を直接返し、高速な応答時間を実現します。

インテリジェントな推論を有効にするには、prompt_extend=true を設定します。有効にすると、システムは最適化されたプロンプトおよび推論プロセスを画像とともに返しますが、応答時間が延長されます。

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "z-image-turbo",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist.  The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.”  Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement.  Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": false,
        "size": "1024*1024"
    }
}'

リクエストヘッダー

Content-Type 文字列 (必須)

リクエストのコンテンツタイプ。必ず application/json を指定してください。

Authorization 文字列 (必須)

Model Studio API キーを使用した認証資格情報。

例:Bearer sk-xxxx

リクエスト本文

model 文字列 (必須)

モデル名。必ず z-image-turbo を指定してください。

input オブジェクト (必須)

基本的な入力情報。

プロパティ

messages 配列 (必須)

リクエストコンテンツの配列。現在はシングルターンの会話のみをサポートしています。ロールとコンテンツのパラメーターを 1 組だけ渡してください。マルチターンの会話はサポートされていません。

プロパティ

role 文字列 (必須)

メッセージのロール。このパラメーターを user に設定します。

content 配列 (必須)

メッセージコンテンツの配列。必ず 1 つのテキストオブジェクトのみを含めてください。

プロパティ

text 文字列(必須)

正のプロンプトは、希望する画像の内容、スタイル、構成を記述します。

中国語および英語をサポートします。長さは 800 文字以内である必要があります。漢字、英字、数字、記号のいずれも 1 文字としてカウントされます。超過分は自動的に切り捨てられます。

例:喜びに満ちた表情の座っているオレンジ色の猫で、生き生きとしていて可愛らしく、リアリスティックかつ正確です。

注意:テキストオブジェクトは 1 つだけサポートされます。0 個または複数を渡すとエラーになります。

parameters オブジェクト (任意)

画像編集パラメーター。

プロパティ

size 文字列 (任意)

出力画像の解像度。形式は 幅×高さ です。

  • デフォルト値:1024*1536

  • 合計ピクセル数の制限範囲:512×512 ~ 2048×2048 の間。

  • 推奨解像度範囲:より良い画像生成結果を得るためには、合計ピクセル数が 1024×1024 ~ 1536×1536 の範囲が推奨されます。

例:1024*1536。

合計ピクセル数が 1024×1024 の場合の推奨解像度:

  • 1:1:1024*1024

  • 2:3:832*1248

  • 3:2:1248*832

  • 3:4:864*1152

  • 4:3:1152*864

  • 7:9:896*1152

  • 9:7:1152*896

  • 9:16:720*1280

  • 9:21:576*1344

  • 16:9:1280*720

  • 21:9:1344*576

合計ピクセル数が 1280×1280 の場合の推奨解像度:

  • 1:1:1280*1280

  • 2:3:1024*1536

  • 3:2:1536*1024

  • 3:4:1104*1472

  • 4:3:1472*1104

  • 7:9:1120*1440

  • 9:7:1440*1120

  • 9:16:864*1536

  • 9:21:720*1680

  • 16:9:1536*864

  • 21:9:1680*720

合計ピクセル数が 1536×1536 の場合の推奨解像度:

  • 1:1:1536*1536

  • 2:3:1248*1872

  • 3:2:1872*1248

  • 3:4:1296*1728

  • 4:3:1728*1296

  • 7:9:1344*1728

  • 9:7:1728*1344

  • 9:16:1152*2048

  • 9:21:864*2016

  • 16:9:2048*1152

  • 21:9:2016*864

prompt_extend ブール値 (任意)

重要

prompt_extend は課金に直接影響します。true に設定すると、false に設定した場合よりもコストがかかります。詳細については、「モデル価格」をご参照ください。

インテリジェントなプロンプト(テキスト)の書き換えを有効にします。有効にすると、大規模言語モデル(LLM)がプロンプトを最適化し、推論プロセスを出力します。

  • false:デフォルト。インテリジェントな書き換えを無効にします。画像と元のテキストプロンプトを出力します。

  • true:インテリジェントな書き換えを有効にします。画像、最適化されたテキストプロンプト、および推論プロセスを出力します。

seed 整数 (任意)

乱数シード。有効範囲:[0,2147483647]

同じ seed 値を使用すると、結果がより一貫性を持ちます。省略した場合は、アルゴリズムがランダムなシードを使用します。

注意: 生成は確率的であるため、同一の seed 値であっても、完全に同一の結果が保証されるわけではありません。

レスポンスパラメーター

タスク実行成功時

タスクデータ(タスクステータスおよび画像 URL)は 24 時間のみ保持され、その後自動的にパージされます。生成された画像は速やかに保存してください。

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx"
                        },
                        {
                            "text": "Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist.  The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.”  Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement.  Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing."
                        }
                    ],
                    "reasoning_content": "",
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 1024,
        "image_count": 1,
        "input_tokens": 0,
        "output_tokens": 0,
        "total_tokens": 0,
        "width": 1024
    },
    "request_id": "abf1645b-b630-433a-92f6-xxxxxx"
}

タスク実行失敗時

タスクの実行に失敗した場合、エラーの詳細を含むレスポンスが返されます。code および message フィールドが失敗の原因を示します。詳細については、「エラーメッセージ」をご参照ください。

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

output オブジェクト

タスクの出力情報。

プロパティ

choices 配列

モデルによって生成された出力。この配列には、必ず 1 つの要素のみが含まれます。

プロパティ

finish_reason 文字列

タスクが停止した理由。正常終了の場合、この値は stop です。

message オブジェクト

モデルが返すメッセージ。

プロパティ

role 文字列

メッセージのロール。この値は常に assistant です。

content 配列

プロパティ

image 文字列

生成された画像の URL。画像フォーマットは PNG です。URL の有効期限は 24 時間です。 速やかにダウンロードおよび保存してください。

text 文字列

  • prompt_extend=false の場合:入力プロンプトです。

  • prompt_extend=true の場合:書き換えられたプロンプトです。

reasoning_content 文字列

モデルの推論プロセス。prompt_extend=true の場合のみ返されます。

usage オブジェクト

出力使用状況の統計情報。成功した結果のみがカウントされます。

プロパティ

width 整数

生成された画像の幅(ピクセル単位)。

height 整数

生成された画像の高さ(ピクセル単位)。

image_count 整数

生成された画像の枚数。値は固定で 1 です。

input_tokens 整数

入力トークン数。prompt_extend が false の場合、値は 0 です。

output_tokens 整数

出力トークン数。prompt_extend が false の場合、値は 0 です。

output_tokens_details オブジェクト

出力トークンに関する詳細情報。prompt_extend が true の場合のみ返されます。

プロパティ

reasoning_tokens 整数

推論に使用されたトークン数。

total_tokens 整数

トークンの合計数。prompt_extend が false の場合、値は 0 です。

request_id 文字列

リクエストの一意の識別子。トレーシングおよびトラブルシューティングに使用します。

code 文字列

エラーコード。リクエストが失敗した場合のみ返されます。「エラーコード」をご参照ください。

message 文字列

詳細なエラーメッセージ。リクエストが失敗した場合のみ返されます。「エラーコード」をご参照ください。

制限事項

  • 画像の url は 24 時間のみ保持されます。速やかにダウンロードしてください。

  • コンテンツモデレーション:入力 prompt および出力画像の両方がコンテンツモデレーションの対象となります。禁止されたコンテンツを含むリクエストは、IPInfringementSuspect または DataInspectionFailed エラーを引き起こします。「エラーコード」をご参照ください。

課金およびレート制限

  • モデルの無料クォータおよび単位課金価格については、「モデル価格」をご参照ください。

  • モデルのレート制限については、「Z-Image」をご参照ください。

  • 課金は、正常に生成された画像の枚数に基づきます。これは、インテリジェントな書き換えが有効かどうかに依存します。モデル呼び出しの失敗や処理エラーは、課金対象とはならず、無料クォータを消費しません。

エラーコード

モデル呼び出しが失敗してエラーメッセージを返した場合、「エラーメッセージ」をご参照ください。

よくある質問

Q:モデル呼び出しのメトリックを確認するにはどうすればよいですか?

A:モデル呼び出しの完了から 1 時間後、モデルモニタリング(シンガポール) または モデルモニタリング(中国 (北京)) ページに移動して、呼び出し回数や成功率などのメトリックを確認できます。詳細については、「課金照会およびコスト管理」をご参照ください。

Q:画像ストレージ用のドメイン名ホワイトリストを取得するにはどうすればよいですか?

A:モデルによって生成された画像は OSS に保存されます。API は一時的なパブリック URL を返します。このダウンロード URL 用のファイアウォールホワイトリストを設定するには、以下の点にご注意ください。基盤となるストレージは動的に変更される可能性があります。このトピックでは、古くなった情報によるアクセス障害を防ぐため、固定の OSS ドメイン名ホワイトリストを提供していません。セキュリティ制御が必要な場合は、アカウントマネージャーに連絡して、最新の OSS ドメイン名リストを取得してください。