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

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

最終更新日:Jun 04, 2026

高速な生成が可能な軽量 Text-to-Image モデルで、中国語および英語のテキストレンダリングと柔軟な解像度をサポートします。

オンラインで試す: (シンガポール | 中国 (北京)) | 技術ブログ

使用例

入力プロンプト

出力画像

スタイリッシュな若い女性の写真。短い黒髪で、活気ある漫画風の壁画の前に自信を持って立っている。全身黒の衣装を着用:フリル付きカラーのふっくらとしたボンバー ジャケット、カーゴショートパンツ、フィッシュネットタイツ、ずっしりとした黒のドクターマーチン、腰からゴールドチェーンがぶら下がっている。背景には4つのカラフルなコミック風パネルがある:1つは「GRAND STAGE」と表示され、スニーカーとゲータレードのボトルが含まれる;もう1つは緑のナイキ スニーカーとピザのスライスを表示;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 キーを環境変数として設定します。

同期 HTTP 呼び出し

シンガポール: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

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

WorkspaceId は、実際の ワークスペース ID に置き換えてください。

リクエストパラメーター

Text-to-Image

この例では、より高速な応答のために画像を直接返します。インテリジェントなプロンプトリライトを有効にするには、prompt_extend=true を設定してください。この場合、システムは最適化されたプロンプト、推論内容、および画像を返します(応答時間が長くなります)。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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 string (必須)

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

Authorization string (必須)

Model Studio API キーを使用してリクエストを認証します。例:Bearer sk-xxxx。

リクエスト本文

model string (必須)

モデル名:z-image-turbo。

input object (必須)

入力内容。

プロパティ

messages array (必須)

リクエスト内容の配列。シングルターンのみ対応です。1 組のロールとコンテンツを渡してください。マルチターンはサポートされていません。

プロパティ

role string (必須)

メッセージのロール:user

content array (必須)

メッセージ内容の配列。1 つのテキストオブジェクトを含む必要があります。

プロパティ

text string (必須)

希望する内容、スタイル、構図を記述するポジティブプロンプト。

中国語および英語をサポートします。最大 800 文字(文字、アルファベット、数字、記号のいずれも 1 文字としてカウント)です。超過分は切り捨てられます。

例:幸せそうな表情をした座っているオレンジ色の猫。生き生きとして可愛らしく、リアルで正確。

注記:テキストオブジェクトは 1 つのみサポートされます。ゼロ個または複数のテキストオブジェクトを渡すとエラーが返されます。

parameters object (任意)

画像生成パラメーター。

プロパティ

size string (任意)

出力画像の解像度を幅×高さ形式で指定します。

  • デフォルト: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 bool (任意)

重要

prompt_extend を有効にするとコストが増加します。詳細については、モデルの課金をご参照ください。

LLM による最適化と推論出力を通じて、インテリジェントなプロンプトリライトを有効にします。

  • false (デフォルト):画像と元のプロンプトを返します

  • true:画像、最適化されたプロンプト、および推論内容を返します

seed integer (任意)

乱数シード。有効範囲:[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 object

モデルの出力。

プロパティ

choices array

モデルの出力内容。配列には 1 つの要素が含まれます。

プロパティ

finish_reason string

完了理由。stop の値は成功を示します。

message object

モデルの応答メッセージ。

プロパティ

role string

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

content array

プロパティ

image string

生成された画像の URL (PNG)。24 時間有効です。速やかにダウンロードしてください。

text string

これは、入力プロンプト (prompt_extend=false の場合) または書き直されたプロンプト (prompt_extend=true の場合) を返します。

reasoning_content string

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

usage object

これは、正常に生成された場合の使用量統計情報のみを含みます。

プロパティ

width integer

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

height integer

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

image_count integer

生成された画像の枚数:1。

input_tokens integer

入力トークン数 (prompt_extend=false の場合は 0)。

output_tokens integer

出力トークン数 (prompt_extend=false の場合は 0)。

output_tokens_details object

出力トークンの詳細 (prompt_extend=true の場合のみ)。

プロパティ

reasoning_tokens integer

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

total_tokens integer

合計トークン数 (prompt_extend=false の場合は 0)。

request_id string

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

code string

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

message string

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

制限事項

  • 画像 URL の有効期限は 24 時間です。速やかにダウンロードしてください。

  • コンテンツモデレーション:入力 プロンプト および出力画像の両方がコンテンツモデレーションの対象となります。準拠していないコンテンツの場合、IPInfringementSuspect または DataInspectionFailed エラーが返されます。エラーコードをご参照ください。

課金とレート制限

  • 価格と無料クォータについては、モデルの課金をご参照ください。

  • レート制限については、Z-Imageをご参照ください。

  • 課金は、正常に生成された画像の枚数および prompt_extend の状態に基づいて行われます。失敗した呼び出しは料金が発生せず、無料クォータも消費しません。

エラーコード

失敗した呼び出しのトラブルシューティングについては、エラーコードをご参照ください。

よくある質問

Q:モデル呼び出しのメトリックを確認する方法を教えてください。

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

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

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