Skip to main content

Image and video understanding

視覚理解モデルは、提供された画像や動画に基づいて質問に回答できます。単一または複数の画像入力に対応し、画像キャプション、視覚質問応答、物体位置特定など、さまざまなタスクに適しています。

オンラインで試す:Alibaba Cloud Model Studio コンソールに移動します。ページの右上隅で、ターゲットリージョンを選択します。その後、Vision Models ページに移動してモデルを試します。

はじめに

前提条件
  • API キーを取得し、環境変数として設定します。
  • SDK を使用して呼び出しを行うには、SDK をインストールします。DashScope Python SDK はバージョン 1.24.6 以降、DashScope Java SDK はバージョン 2.21.10 以降である必要があります。
以下の例は、モデルを呼び出して画像の内容を説明する方法を示しています。ローカルファイルと画像の制限に関する詳細については、「ローカルファイルの渡し方」および「画像の制限」をご参照ください。
  • OpenAI 互換
  • DashScope
  • Python
  • Node.js
  • Java
  • curl
from openai import OpenAI
import os

client = OpenAI(
    # API キーはリージョンによって異なります。API キーを取得するには、https://www.alibabacloud.com/help/ja/model-studio/get-api-key をご参照ください
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 次の URL はシンガポールリージョン用です。呼び出しを行う際に、{WorkspaceId} を実際のワークスペース ID に置き換えてください。URL はリージョンによって異なります。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

completion = client.chat.completions.create(
    model="qwen3.8-max",  # この例では qwen3.7-plus を使用しています。必要に応じて他のモデルに置き換えることができます。モデルのリストについては、https://www.alibabacloud.com/help/model-studio/getting-started/models をご参照ください
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
                    },
                },
                {"type": "text", "text": "画像にはどのようなシーンが描かれていますか?"},
            ],
        },
    ],
)
print(completion.choices[0].message.content)

応答

これはビーチで撮影された写真です。写真には、人と犬が砂の上に座っており、背景には海と空が写っています。人と犬は交流しているようで、犬の前足が人の手に乗っています。フレームの右側から太陽光が差し込み、シーンに暖かい雰囲気を加えています。

モデルのパフォーマンス

画像 Q&A

画像の内容を説明したり、人物、場所、動物、植物などを識別して分類・ラベル付けしたりします。

p1021359

この画像の中で、太陽が眩しすぎるときに使うべきアイテムは何ですか?

太陽が眩しすぎる場合は、画像にあるピンクのサングラスを使用すべきです。サングラスは強い光を効果的に遮断し、紫外線による目へのダメージを軽減し、明るい日差しの中での視力を保護し、視覚的な快適さを向上させるのに役立ちます。

クリエイティブライティング

画像や動画の内容に基づいて鮮やかなテキスト記述を生成し、物語の執筆、コピーライティング、ショートビデオのスクリプトなどのクリエイティブなシナリオに適しています。

vl-Q&A

画像の内容に基づいて、面白い SNS 投稿を作成してください。

承知いたしました。この画像は豊かな中秋節の雰囲気に満ちており、古典的な要素と現代的な要素を巧みに組み合わせています。画像内の主要な要素に基づいて、異なるスタイルの SNS 投稿をいくつかご用意しましたので、お選びください。

詩的で美しいスタイル

今宵、月は誰の目にも明るく輝くが、秋の想いがどこに落ちるかは誰にもわからない。嫦娥は月に飛び、玉兎は薬をつく。古人のロマンスが今宵、灯される。この明るい月があなたの帰り道を照らし、私の深い想いを運びますように。中秋節おめでとうございます!

温かい願いのスタイル

月は満ち、人々は再会する。中秋の夜は最も穏やかだ。花火が咲くのを見て、空に浮かぶ満月を愛で、月餅を一口食べ、健康を願う。あなたと私の願いがすべて叶いますように。皆様、中秋節おめでとうございます。ご家族が幸せでありますように!

テキスト認識と情報抽出

画像内のテキストや数式を認識したり、領収書、証明書、フォームから情報を抽出したりします。フォーマットされたテキスト出力に対応しています。

-q2cdz6jy89b6m3kp

画像から次の情報を抽出してください:['請求書コード', '請求書番号', '目的地', '燃料サーチャージ', '運賃', '日付', '出発時刻', '列車番号', '座席番号']。JSON 形式で出力してください。

{

"Invoice Code": "221021325353",

"Invoice Number": "10283819",

"Destination": "開発区",

"Fuel Surcharge": "2.0",

"Fare": "8.00<Full>",

"Date": "2013-06-29",

"Departure Time": "随時",

"Train Number": "040",

"Seat Number": "371"

}

多分野にわたる問題解決

画像内の数学、物理、化学などの問題を解決します。K-12、大学、成人教育に適しています。

-5jwcstcvmdpqghaj

グラフ内の数学の問題を段階的に解いてください。

-answer

ビジュアルプログラミング

画像や動画からコードを生成します。この機能を使用して、デザイン案、ウェブサイトのスクリーンショットなどから HTML、CSS、JS コードを生成できます。

code

私のスケッチに基づいて、HTML と CSS を使用してウェブページを作成してください。メインカラーは黒にしてください。

code-preview

ウェブページのプレビュー

物体位置特定

2D および 3D の位置特定に対応しています。この機能を使用して、物体の向き、視点の変化、およびオクルージョン関係を判断できます。3D 位置特定は、Qwen3-VL モデルに追加された新機能です。
Qwen2.5-VL モデルの物体位置特定性能は、480 × 480 から 2560 × 2560 の解像度範囲内で安定しています。この範囲外では、検出精度が低下し、時折検出フレームのドリフトが発生する可能性があります。
位置特定の結果を元の画像に描画する方法については、「よくある質問」をご参照ください。
2D 位置特定
-530xdcos1lqkcfuy
  • Box (バウンディングボックス) 座標を返す:画像内のすべての食品を検出し、その bbox 座標を JSON 形式で出力します。
  • Point (重心) 座標を返す:画像内のすべての食品を点として特定し、その点座標を XML 形式で出力します。
2D 位置特定結果の可視化
-mu9podu1eyvph1zd
3d
画像内の車を検出し、その 3D 位置を予測します。出力 JSON:[{"bbox_3d": [x_center, y_center, z_center, x_size, y_size, z_size, roll, pitch, yaw], "label": "category"}]。
3d-result

ドキュメント解析

画像ベースのドキュメント (スキャンコピーや画像 PDF など) を QwenVL HTML または QwenVL Markdown 形式に解析します。この形式は、テキストを正確に認識するだけでなく、画像や表などの要素の位置情報も取得します。Qwen3-VL モデルでは、Markdown 形式への解析機能が追加されました。
推奨されるプロンプトは次のとおりです:qwenvl html (HTML 形式に解析する場合) または qwenvl markdown (Markdown 形式に解析する場合)。

image

qwenvl markdown.

-result

結果の可視化

動画理解

特定のイベントの位置特定やタイムスタンプの取得、主要な時間帯の要約生成など、動画コンテンツを分析します。
動画内の人物の一連の行動を説明してください。開始時刻 (start_time)、終了時刻 (end_time)、およびイベント (event) を JSON 形式で出力してください。タイムスタンプには HH:mm:ss を使用してください。{"events": [{"start_time": "00:00:00","end_time": "00:00:05","event": "人物が段ボール箱を持ってテーブルに向かって歩き、テーブルの上に置きます。"},{"start_time": "00:00:05","end_time": "00:00:15","event": "人物がスキャナーを手に取り、段ボール箱のラベルをスキャンします。"},{"start_time": "00:00:15","end_time": "00:00:21","event": "人物がスキャナーを元の場所に戻し、ペンを手に取ってノートに情報を記録します。"}]}

コア機能

思考モードの有効化または無効化

  • qwen3.8、qwen3.7、qwen3.6、qwen3.5、qwen3-vl-plus シリーズのモデルは、ハイブリッド思考モデルです。応答する前に思考することも、直接応答することもできます。enable_thinking パラメーターを使用して、思考モードを有効にするかどうかを制御します:
    • true:思考モードを有効にします。qwen3.8、qwen3.7、qwen3.6、および qwen3.5 シリーズのモデルのデフォルト値は true です。
    • false:思考モードを無効にします。qwen3-vl-plus シリーズのモデルのデフォルト値は false です。
  • thinking サフィックスを持つモデルは、思考専用モデルです。常に応答する前に思考し、この機能は無効にできません。
  • モデル構成:Agent ツール呼び出しを伴わない一般的な会話シナリオでは、最適なパフォーマンスを維持するために System Message を設定しないでください。モデルのロール設定や出力形式の要件などの命令は、User Message を通じて渡すことができます。
  • ストリーミング出力を優先:思考モードが有効な場合、ストリーミングと非ストリーミングの両方の出力がサポートされます。応答が長すぎることによるタイムアウトを避けるために、ストリーミング出力を優先して使用してください。
  • 思考の長さを制限:ディープシンキングモデルは、時々長い推論プロセスを出力することがあります。thinking_budget パラメーターを使用して、思考プロセスの長さを制限できます。モデルの思考プロセス中に生成されたトークン数が thinking_budget を超えると、推論コンテンツは切り捨てられ、モデルはすぐに最終応答の生成を開始します。thinking_budget のデフォルト値は、モデルの最大 Chain-of-Thought 長です。詳細については、モデルリストをご参照ください。
  • OpenAI 互換
  • DashScope
enable_thinking パラメーターは標準の OpenAI パラメーターではありません。OpenAI Python SDK を使用する場合は、extra_body を通じて渡してください。
import os
from openai import OpenAI

client = OpenAI(
    # API キーはリージョンによって異なります。API キーを取得するには、https://www.alibabacloud.com/help/ja/model-studio/get-api-key をご参照ください
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 次の URL はシンガポールリージョン用です。呼び出しを行う際に、{WorkspaceId} を実際のワークスペース ID に置き換えてください。URL はリージョンによって異なります。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

reasoning_content = ""  # 完全な思考プロセスを定義します
answer_content = ""     # 完全な応答を定義します
is_answering = False   # 思考プロセスを終了して応答を開始するかどうかを判断します
enable_thinking = True
# チャット補完リクエストを作成します
completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"
                    },
                },
                {"type": "text", "text": "この問題の解き方を教えてください。"},
            ],
        },
    ],
    stream=True,
    # enable_thinking パラメーターは思考プロセスを有効にし、thinking_budget パラメーターは推論プロセスの最大トークン数を設定します。
    # enable_thinking パラメーターを使用して思考モードを切り替えます。
    extra_body={
        'enable_thinking': enable_thinking,
        "thinking_budget": 81920},

    # 最後のチャンクでトークン使用量を返すには、次の行のコメントを解除します。
    # stream_options={
    #     "include_usage": True
    # }
)

if enable_thinking:
    print("\n" + "=" * 20 + "思考プロセス" + "=" * 20 + "\n")

for chunk in completion:
    # chunk.choices が空の場合は、使用量を出力します。
    if not chunk.choices:
        print("\n使用量:")
        print(chunk.usage)
    else:
        delta = chunk.choices[0].delta
        # 思考プロセスを出力します。
        if hasattr(delta, 'reasoning_content') and delta.reasoning_content is not None:
            print(delta.reasoning_content, end='', flush=True)
            reasoning_content += delta.reasoning_content
        else:
            # 応答を開始します。
            if delta.content != "" and is_answering is False:
                print("\n" + "=" * 20 + "完全な応答" + "=" * 20 + "\n")
                is_answering = True
            # 応答プロセスを出力します。
            print(delta.content, end='', flush=True)
            answer_content += delta.content

# print("=" * 20 + "完全な思考プロセス" + "=" * 20 + "\n")
# print(reasoning_content)
# print("=" * 20 + "完全な応答" + "=" * 20 + "\n")
# print(answer_content)

複数画像の入力

視覚理解モデルは、1 回のリクエストで複数の画像を渡すことをサポートしており、製品比較や複数ページのドキュメント処理などのタスクに使用できます。これを行うには、user message の content 配列に複数の画像オブジェクトを含めるだけです。
画像数は、モデルの画像とテキストの合計トークン制限によって制限されます。すべての画像とテキストの合計トークン数は、モデルの最大入力を超えてはなりません。
  • OpenAI 互換
  • DashScope
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # API キーはリージョンによって異なります。API キーを取得するには、https://www.alibabacloud.com/help/ja/model-studio/get-api-key をご参照ください
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 次の URL はシンガポールリージョン用です。呼び出しを行う際に、{WorkspaceId} を実際のワークスペース ID に置き換えてください。URL はリージョンによって異なります。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",  #  この例では qwen3.7-plus を使用しています。必要に応じて他のモデルに置き換えることができます。モデルのリストについては、https://www.alibabacloud.com/help/model-studio/getting-started/models をご参照ください
    messages=[
        {"role": "user","content": [
            {"type": "image_url","image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"},},
            {"type": "image_url","image_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"},},
            {"type": "text", "text": "これらの画像にはどのような内容が描かれていますか?"},
            ],
        }
    ],
)

print(completion.choices[0].message.content)

応答

画像 1 は、ビーチで女性とラブラドールレトリバーが交流しているシーンを示しています。女性はチェック柄のシャツを着て砂の上に座り、犬と握手しています。背景は海の波と空で、写真全体が暖かさと喜びに満ちています。

画像 2 は、森の中を歩く虎のシーンを示しています。虎の毛皮はオレンジ色で黒い縞模様があります。虎は前に進んでおり、周りには密集した木々や植物があり、地面は落ち葉で覆われています。写真全体が野生の自然を感じさせます。

動画理解

視覚理解モデルは、画像リスト (ビデオフレーム) またはビデオファイルとして提供される動画コンテンツを理解できます。以下の例は、URL で指定されたオンライン動画または画像リストを理解する方法を示しています。動画の制限や画像リストで渡せる画像数に関する詳細については、「動画の制限」をご参照ください。
動画ファイルを理解する際のパフォーマンスを向上させるには、最新または最近のスナップショットバージョンのモデルを使用してください。
  • ビデオファイル
  • 画像リスト
視覚理解モデルは、動画から一連のフレームを抽出して動画コンテンツを分析します。以下の 2 つのパラメーターでフレーム抽出戦略を制御できます:
  • fps:フレーム抽出の頻度を制御します。1/fps 秒ごとに 1 フレームが抽出されます。値の範囲は [0.1, 10] で、デフォルト値は 2.0 です。
    • 動きの速いシーンでは、より多くの詳細を捉えるために fps 値を高く設定します。
    • 静的なシーンや長い動画では、パフォーマンスを向上させるために fps 値を低く設定します。
  • max_frames:動画から抽出する最大フレーム数。システムは動画の fps に基づいて合計フレーム数を計算します。合計フレーム数がこの制限を超えた場合、システムは制限を満たすようにフレームを均等にサンプリングします。このパラメーターは DashScope SDK を使用する場合にのみ利用可能です。
  • OpenAI 互換
  • DashScope
OpenAI SDK または HTTP を使用してビデオファイルを視覚理解モデルに直接送信する場合、ユーザーメッセージの "type" パラメーターを "video_url" に設定します。
Python
import os
from openai import OpenAI

client = OpenAI(
    # API キーはリージョンによって異なります。API キーを取得するには、https://www.alibabacloud.com/help/ja/model-studio/get-api-key をご参照ください
    # 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 次の URL はシンガポールリージョン用です。呼び出しを行う際に、{WorkspaceId} をワークスペース ID に置き換えてください。URL はリージョンによって異なります。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "user",
            "content": [
                # ビデオファイルを直接渡す場合、type の値を video_url に設定します。
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4"
                    },
                    "fps": 2
                },
                {
                    "type": "text",
                    "text": "この動画の内容は何ですか?"
                }
            ]
        }
    ]
)

print(completion.choices[0].message.content)

ローカルファイルの渡し方 (Base64 エンコーディングまたはファイルパス)

視覚理解モデルは、ローカルファイルをアップロードするための 2 つの方法をサポートしています:Base64 エンコーディングと直接ファイルパスアップロード。ファイルサイズと SDK の種類に基づいてアップロード方法を選択できます。推奨事項については、「ファイルアップロード方法の選択方法」をご参照ください。どちらの方法も、「画像の制限」で説明されているファイル要件を満たす必要があります。
  • Base64 エンコーディングを使用したアップロード
  • ファイルパスを使用したアップロード
ファイルを Base64 エンコードされた文字列に変換し、モデルに渡します。この方法は、OpenAI および DashScope SDK、および HTTP リクエストに適用できます。
  1. ファイルのエンコード:ローカル画像を Base64 エンコーディングに変換します。
    # エンコード関数:ローカルファイルを Base64 エンコードされた文字列に変換します
    import base64
    def encode_image(image_path):
        with open(image_path, "rb") as image_file:
            return base64.b64encode(image_file.read()).decode("utf-8")
    
    # xxx/eagle.png をローカル画像の絶対パスに置き換えてください
    base64_image = encode_image("xxx/eagle.png")
    
  2. 次の形式で Data URL を構築します:data:[MIME_type];base64,{base64_image}。
    1. MIME_type を実際のメディアタイプに置き換えます。サポートされている画像形式 テーブルの MIME Type 値と一致することを確認してください (例:image/jpeg または image/png)。
    2. base64_image は、前のステップで生成された Base64 文字列です。
  3. モデルの呼び出し:image または image_url パラメーターを使用して Data URL を渡します。
  • 画像
  • ビデオファイル
  • 画像リスト
  • ファイルパスを使用した渡し方
  • Base64 エンコードされた入力
Python
import os
import dashscope

# 以下の設定はシンガポールリージョン用です。API を呼び出す際に、{WorkspaceId} を実際のワークスペース ID に置き換えてください。region の値はリージョンによって異なります。
client = dashscope.Client(
    # 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください:api_key="sk-xxx"
    # API キーはリージョンによって異なります。API キーを取得するには、https://www.alibabacloud.com/help/ja/model-studio/get-api-key をご参照ください
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# xxx/eagle.png をローカル画像の絶対パスに置き換えてください
local_path = "xxx/eagle.png"
image_path = f"file://{local_path}"
messages = [
                {'role':'user',
                'content': [{'image': image_path},
                            {'text': '画像にはどのようなシーンが描かれていますか?'}]}]
response = client.multimodal.chat.create(
    model='qwen3.7-plus',  # この例では qwen3.7-plus を使用しています。必要に応じてモデル名を変更できます。モデルのリストについては、https://www.alibabacloud.com/help/model-studio/getting-started/models をご参照ください
    messages=messages)
print(response.output_text)

高解像度画像の処理

視覚理解モデル API には、単一のエンコードされた画像の視覚トークン数に制限があります。デフォルト設定では、高解像度画像は圧縮されるため、詳細が失われ、理解精度に影響を与える可能性があります。vl_high_resolution_images を有効にするか、max_pixels を調整して視覚トークン数を増やすことができます。これにより、より多くの画像の詳細が保持され、理解が向上します。
入力画像のピクセル数がモデルのピクセル制限を超えると、画像は制限内に収まるようにダウンスケールされます。

モデル

トークンあたりのピクセル数

vl_high_resolution_images

max_pixels

トークン制限

ピクセル制限

Qwen3.8、Qwen3.7、Qwen3.6、Qwen3.5 および Qwen3-VL シリーズのモデル

32×32

true

max_pixels は無効です

16,384 トークン

16,777,216 (つまり、16,384 × 32 × 32)

false (デフォルト)

カスタマイズ可能。デフォルト値は 2,621,440 で、最大値は 16,777,216 です。

max_pixels によって決定され、max_pixels / 32 / 32 です

max_pixels

オープンソース Qwen2.5-VL シリーズ、および QVQ シリーズのモデル

28 × 28

true

max_pixels は無効です

16,384 トークン

12,845,056 (つまり、16,384 × 28 × 28)

false (デフォルト)

カスタマイズ可能。デフォルト値は 1,003,520 で、最大値は 12,845,056 です。

max_pixels によって決定され、max_pixels / 28 / 28 です

max_pixels

  • vl_high_resolution_images=true の場合、API は固定解像度ポリシーを使用し、max_pixels 設定を無視します。これは、画像内の細かいテキスト、小さなオブジェクト、または豊富な詳細を認識するのに適しています。
  • vl_high_resolution_images=false の場合、最終的なピクセル制限は max_pixels パラメーターの値に依存します。
    • 視覚トークンの消費を削減したいコストに敏感なシナリオの場合:max_pixels のデフォルト値を使用するか、より小さい値に設定します。max_pixels は主に視覚トークンの数と呼び出しコストに影響します。私たちのテストでは、これを下げてもエンドツーエンドの応答時間に大きな影響はありませんでした。
    • 特定の詳細に焦点を当て、処理速度の低下を受け入れられる場合は、必要に応じて max_pixels の値を増やしてください。
  • OpenAI 互換
  • DashScope
vl_high_resolution_images は標準の OpenAI パラメーターではありません。これを渡す方法は、言語 SDK によって異なります:
  • Python SDK:extra_body ディクショナリを通じて渡す必要があります。
  • Node.js SDK:トップレベルのパラメーターとして直接渡すことができます。
Python
import os
import time
from openai import OpenAI

client = OpenAI(
    # API キーはリージョンによって異なります。API キーを取得するには、https://www.alibabacloud.com/help/ja/model-studio/get-api-key をご参照ください
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 次の URL はシンガポールリージョン用です。API を呼び出す際に、{WorkspaceId} を実際のワークスペース ID に置き換えてください。URL はリージョンによって異なります。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "user","content": [
            {"type": "image_url","image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250212/earbrt/vcg_VCG211286867973_RF.jpg"},
            # max_pixels は入力画像の最大ピクセルしきい値を表します。vl_high_resolution_images=True の場合は無効です。vl_high_resolution_images=False の場合はカスタマイズ可能で、最大値はモデルによって異なります。
            # "max_pixels": 16384 * 32 * 32
            },
           {"type": "text", "text": "この画像はどのような祭りの雰囲気を伝えていますか"},
            ],
        }
    ],
    extra_body={"vl_high_resolution_images":True}

)
print(f"モデルの出力: {completion.choices[0].message.content}")
print(f"合計入力トークン: {completion.usage.prompt_tokens}")

その他の使用法

使用制限

入力ファイルの制限

  • 画像の制限
  • 動画の制限
  • 画像解像度:
    • 最小サイズ:画像の幅と高さは両方とも 10 ピクセルより大きい必要があります。
    • アスペクト比:元画像とスケーリングされた画像の両方で、長辺と短辺の比率が 200:1 を超えてはなりません。
      画像のスケーリングロジックについては、「画像トークンの計算smart_resize
    • 最大ピクセル数:
      • 画像解像度を 8K (7680x4320) 以内に保ってください。より高い解像度の画像は、ファイルサイズが大きく、ネットワーク転送時間が長くなるため、API 呼び出しのタイムアウトを引き起こす可能性があります。
      • 自動スケーリング:モデルは max_pixels と min_pixels を使用して画像サイズを調整できます。高解像度の画像を提供しても検出精度は向上せず、むしろ呼び出し失敗のリスクが高まります。アップロードする前に、クライアント側で画像を適切なサイズにスケーリングしてください。
  • サポートされている画像形式
    • 4K (3840x2160) 未満の解像度では、次の画像形式がサポートされています:

      画像形式

      一般的な拡張子

      MIME タイプ

      BMP

      .bmp

      image/bmp

      JPEG

      .jpe, .jpeg, .jpg

      image/jpeg

      PNG

      .png

      image/png

      TIFF

      .tif, .tiff

      image/tiff

      WEBP

      .webp

      image/webp

      HEIC

      .heic

      image/heic

    • 4K (3840x2160) と 8K (7680x4320) の間の解像度では、JPEG、JPG、および PNG 形式のみがサポートされています。
  • 画像サイズ: 以下の制限は個々の画像ごとに適用されます。複数画像の入力の場合、各画像は独立して評価され、サイズは合計されません。
    • パブリック URL として渡す場合:Qwen3.8、Qwen3.7、Qwen3.6、および Qwen3.5 と Qwen3-VL シリーズのモデルでは、単一の画像は 20 MB を超えることはできません。その他のモデルでは、単一の画像は 10 MB を超えることはできません。
    • ローカルパスとして渡す場合:単一の画像は 10 MB を超えることはできません。
    • Base64 エンコーディングとして渡す場合 (OpenAI 互換 API):Qwen3.8、Qwen3.7、Qwen3.6、Qwen3.5 および Qwen3-VL シリーズのモデルでは、エンコード前の元の画像ファイルは 20 MB を超えることはできません。その他のモデルでは、10 MB を超えることはできません。どちらの場合も、結果の Data URI 文字列は 20 MB を超えることはできません。
    • Base64 エンコーディングとして渡す場合 (Anthropic 互換 API):リクエストボディの合計は6 MBを超えることはできません。複数の画像を渡す場合、このクォータを共有します。
    これらの制限は使用するモデルによって異なります。上位のプランを購入したり、モデルのバージョンをアップグレードしたりしても、これらの制限を引き上げることはできません。
    ファイルを圧縮するには、「画像または動画を必要なサイズに圧縮する方法」をご参照ください。
  • 画像数量制限:複数画像入力でサポートされる最大画像数は、入力方法によって異なります:
    • パブリック URL またはローカルパスとして渡す場合:
      • Qwen3.8-Max、Qwen3.8-Flash、Qwen3.7-Plus シリーズ:最大 2,048 枚の画像
      • Qwen3.7-Flash、Qwen3.6-Plus、Qwen3.6-Flash、Qwen3.5-Plus、Qwen3.5-Flash、Qwen3-VL、Qwen-VL、QVQ シリーズ:最大 256 枚の画像
      • Qwen-Omni シリーズについては、「Omni-modal」をご参照ください。
    • Base64 エンコードされた文字列として渡す場合:最大 250 枚の画像
すべての画像の合計トークン数も、モデルの最大入力トークン制限によって制限されます。すべての画像とテキストの合計トークン数は、モデルの最大入力を超えてはなりません。

ファイル入力方法

  • パブリック URL:HTTP または HTTPS プロトコルをサポートする公開アクセス可能なファイルアドレスを提供します。最適な安定性とパフォーマンスを得るには、ファイルを OSS にアップロードしてパブリック URL を取得します。Model Studio は、-internal を含む OSS 内部エンドポイント (例:https://<bucket>.oss-cn-hangzhou-internal.aliyuncs.com/image.jpg) にアクセスできません。内部アドレスを渡すと、ファイルのダウンロードに失敗し、InvalidParameter が返され、メッセージ Failed to download multimodal content が表示されます。代わりに、OSS パブリックエンドポイント (例:https://<bucket>.oss-cn-hangzhou.aliyuncs.com/image.jpg) または署名付き OSS URL を使用してください。
    モデルがファイルを正常にダウンロードできるようにするには、パブリック URL のレスポンスヘッダーに 必ず Content-Length (ファイルサイズ) と Content-Type (メディアタイプ、例:image/jpeg) を含める必要があります。どちらかのフィールドが欠落しているか、正しくない場合、ファイルのダウンロードは失敗します。
  • Base64 エンコーディング:ファイルを Base64 エンコードされた文字列に変換してから渡します。
  • ローカルファイルパス (DashScope SDK のみ):ローカルファイルのパスを渡します。
ファイル入力方法の選択に関する推奨事項については、「ファイルアップロード方法の選択方法

本番環境での使用

  • 画像と動画の前処理:視覚理解モデルには入力ファイルのサイズ制限があります。ファイルを圧縮するには、「画像または動画の圧縮方法」をご参照ください。
  • テキストファイルの処理:視覚理解モデルは画像と動画ファイルのみをサポートしています。TXT、Word (.doc/.docx)、PDF、またはその他のテキストベースのファイルの処理はサポートしていません。次のいずれかの回避策を使用してください:
    • テキストファイルを画像形式に変換します。Python の pdf2image などの画像処理ライブラリを使用して、ファイルをページごとに複数の高品質な画像に変換します。その後、複数画像入力方法を使用して画像をモデルに渡します。
    • file-id を通じて情報を渡すことで、ドキュメントのアップロードと会話を行うことができる Qwen-Long を使用します。
  • フォールトトレランスと安定性
    • タイムアウト処理:非ストリーミング呼び出しでは、モデルが 300 秒以内に出力生成を完了しない場合、タイムアウトエラーが発生します。タイムアウトが発生すると、生成されたコンテンツがレスポンスボディで返されます。x-dashscope-partialresponse: true を含むレスポンスヘッダーは、応答がタイムアウトしたことを示します。一部のモデルでサポートされている部分補完モード機能を使用します。生成されたコンテンツを messages 配列に追加してリクエストを再送信します。これにより、大規模言語モデル (LLM) はコンテンツの生成を続行できます。詳細については、「不完全な出力からの生成の続行」をご参照ください。
    • クライアント側のタイムアウト構成:前述のタイムアウトは、モデルが 300 秒以内に出力生成を完了しない場合に発生するサーバー側のタイムアウトです。これは、SDK のデフォルトのクライアント側タイムアウトとは異なります。4000 x 4000 ピクセルの画像などの大きな画像を処理する場合、リクエストが SDK のデフォルトのクライアント側タイムアウトよりも長くかかり、サーバー側の 300 秒の制限に達していなくても APITimeoutError で中断されることがあります。これを避けるには、OpenAI Python SDK の with_options を使用してクライアント側のタイムアウトを延長します:
client = client.with_options(timeout=1800.0)
response = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[...]
)
  • ストリーミング出力:stream=True を設定すると、モデルは単一の完全な応答を待つのではなく、コンテンツを増分的に返します。これにより、大きな画像を処理する際の長時間の非ストリーミング呼び出しによるクライアント側のタイムアウトを防ぎます:
stream = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[...],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content)
  • リトライメカニズム:ネットワークの変動や一時的なサービスの利用不能に対処するために、指数バックオフなどの合理的な API 呼び出しリトライロジックを設計します。

課金とレート制限

  • 課金:合計コストは、入力トークンと出力トークンの総数に基づいて計算されます。入力と出力の価格は、Model Studio コンソールで確認できます。
    • トークンの構成:入力トークンは、テキストトークンと、画像または動画から変換されたトークンで構成されます。出力トークンは、モデルによって生成されたテキストです。思考モードでは、モデルの思考プロセスも出力トークンとしてカウントされます。思考モードで思考プロセスが出力されない場合、課金はノンシンキングモードの価格設定に従います。
    • 画像と動画のトークンを計算する:次のコードを使用して、画像または動画のトークン消費量を計算します。推定結果は参照用です。実際の使用量は API 応答に基づきます。
      • 画像
      • 動画
      数式:画像トークン = h_bar * w_bar / token_pixels + 2
      • h_bar, w_bar:スケーリングされた画像の高さと幅。画像を処理する前に、モデルは前処理を実行して特定のピクセル制限まで縮小します。この制限は、max_pixels および vl_high_resolution_images パラメーターの値によって異なります。詳細については、「高解像度画像の処理」をご参照ください。
      • token_pixels:各視覚 token に対応するピクセル値。これはモデルによって異なります:
        • qwen3.8-series、qwen3.7-series、qwen3.6-series、qwen3.5-series、Qwen3-VL:各 token は 32x32 ピクセルに対応します。
        • QVQ およびその他の Qwen2.5-VL モデル:各トークンは 28x28 ピクセルに対応します。
      次のコードは、モデルが使用するおおよその画像スケーリングロジックを示しています。これを使用して画像のトークンを推定します。実際の課金については、API 応答をご参照ください。
      import math
      from PIL import Image  # pip install Pillow
      
      def smart_resize(image_path, max_pixels, vl_high_resolution_images):
          """モデルパラメーターに基づいてスケーリングされた画像のディメンションを計算し、画像トークンを推定します。"""
          image = Image.open(image_path)
          height, width = image.height, image.width
      
          # スケーリング係数は、Qwen3.6、Qwen3.5、Qwen3-VL などのモデルでは 32 です。その他のモデルでは 28 です。
          factor = 32
          h_bar = round(height / factor) * factor
          w_bar = round(width / factor) * factor
      
          # トークンの下限:4 トークン
          min_pixels = 4 * factor * factor
      
          # vl_high_resolution_images=True の場合、トークンの上限は 16384 に固定され、max_pixels は無視されます。
          if vl_high_resolution_images:
              max_pixels = 16384 * factor * factor
      
          # ピクセルの総数を [min_pixels, max_pixels] の範囲に制約します。
          if h_bar * w_bar > max_pixels:
              beta = math.sqrt((height * width) / max_pixels)
              h_bar = math.floor(height / beta / factor) * factor
              w_bar = math.floor(width / beta / factor) * factor
          elif h_bar * w_bar < min_pixels:
              beta = math.sqrt(min_pixels / (height * width))
              h_bar = math.ceil(height * beta / factor) * factor
              w_bar = math.ceil(width * beta / factor) * factor
      
          return h_bar, w_bar
      
      if __name__ == "__main__":
          # 注:max_pixels と vl_high_resolution_images の値は、モデルを呼び出す際に渡されるパラメーターと一致する必要があります。
          h_bar, w_bar = smart_resize("xxx/test.jpg", max_pixels=2560 * 32 * 32, vl_high_resolution_images=False)
          print(f"スケーリングされた画像のディメンション:高さ {h_bar}、幅 {w_bar}")
      
          # 各画像には、1 つの <vision_bos> と 1 つの <vision_eos> トークンが含まれます。
          token = int(h_bar * w_bar / (32 * 32)) + 2
          print(f"画像トークン数:{token}")
      
  • 請求書の表示:Alibaba Cloud 管理コンソールの 課金管理 ページで請求書を表示したり、アカウントにチャージしたりできます。
  • レート制限:視覚理解モデルのレート制限条件に関する詳細については、「レート制限」をご参照ください。
  • 無料クォータ(シンガポールリージョンのみ):視覚理解モデルには 100 万トークンの無料クォータが提供されます。90 日間の有効期間は、Model Studio を有効にした日、またはモデルリクエストが承認された日から始まります。

API リファレンス

視覚理解モデルの入力および出力パラメーターの詳細については、「テキスト生成」をご参照ください。

よくある質問

SDK の種類、ファイルサイズ、ネットワークの安定性に基づいて、最適なアップロード方法を選択してください。

ファイルタイプ

ファイル仕様

DashScope SDK (Python, Java)

OpenAI 互換 / DashScope HTTP

画像

7 MB より大きく 10 MB 未満

ローカルパスを渡す

パブリックネットワーク URL のみサポートされています。 Alibaba Cloud Object Storage Service を使用してください。

7 MB 未満

ローカルパスを渡す

Base64 エンコーディング

動画

100 MB より大きい

パブリックネットワーク URL のみに対応しています。Alibaba Cloud Object Storage Service をご利用ください

パブリックネットワーク URL のみがサポートされています。 Alibaba Cloud Object Storage Service をご利用ください。

7 MB より大きく 100 MB 未満

ローカルパスを渡す

サポートされているのはパブリックネットワーク URL のみです。 Alibaba Cloud Object Storage Service をご利用ください。

7 MB 未満

ローカルパスを渡す

Base64 エンコーディング

Base64 エンコーディングはデータサイズを増加させます。元のファイルサイズは 7 MB 未満である必要があります。
Base64 またはローカルパスを使用して、サーバー側のダウンロードタイムアウトを回避し、安定性を向上させます。
視覚理解モデルには入力ファイルのサイズ制限があります。次の方法を使用してファイルを圧縮してください。
  • オンラインツール: CompressJPEG などを使用して、イメージを圧縮します。
  • ローカルソフトウェア:Photoshop などのソフトウェアを使用して、エクスポート時に品質を調整します。
  • コード実装:
# pip install pillow

from PIL import Image
def compress_image(input_path, output_path, quality=85):
    with Image.open(input_path) as img:
        img.save(output_path, "JPEG", optimize=True, quality=quality)

# ローカル画像を渡します
compress_image("/xxx/before-large.jpeg","/xxx/after-min.jpeg")

# ディレクトリ内の画像をバッチ圧縮します
import glob
import os

def batch_compress(input_dir, output_dir, quality=85):
    files = (
        glob.glob(os.path.join(input_dir, "*.jpg"))
        + glob.glob(os.path.join(input_dir, "*.jpeg"))
        + glob.glob(os.path.join(input_dir, "*.png"))
    )
    for i, f in enumerate(files, 1):
        try:
            compress_image(f, os.path.join(output_dir, os.path.basename(f)), quality)
            print(f"[{i}/{len(files)}] {os.path.basename(f)} 完了")
        except Exception as e:
            print(f"[{i}/{len(files)}] {os.path.basename(f)} エラー: {e}")

batch_compress("/xxx/input_dir", "/xxx/output_dir")
  • オンラインツール:FreeConvert などのオンラインツールを使用して動画を圧縮します。
  • ローカルソフトウェア:HandBrake などのソフトウェアを使用します。
  • コード実装:FFmpeg ツールを使用します。詳細については、FFmpeg 公式ウェブサイトをご参照ください。
# 基本的な変換コマンド
# -i, 機能:入力ファイルパス、例:input.mp4
# -vcodec, 機能:ビデオエンコーダー、一般的な値には libx264 (一般的に推奨) と libx265 (より高い圧縮率) があります
# -crf, 機能:ビデオ品質を制御、値の範囲:[18-28]。値が小さいほど品質が高く、ファイルサイズが大きくなります。
# --preset, 機能:エンコード速度と圧縮効率のバランスを制御します。一般的な値には slow、fast、faster があります。
# -y, 機能:既存のファイルを上書きします (値は不要)
# output.mp4, 機能:出力ファイルパス

ffmpeg -i input.mp4 -vcodec libx264 -crf 28 -preset slow output.mp4
視覚理解モデルが物体位置特定の結果を返した後、次のコードを使用して、元の画像に検出フレームとそのラベル情報を描画できます。
  • Qwen2.5-VL:返される座標は、スケーリングされた画像の左上隅を基準としたピクセル単位の絶対値です。検出フレームを描画するには、qwen2_5_vl_2d.py のコードをご参照ください。
  • Qwen3-VL、Qwen3.5、Qwen3.6、および Qwen3.7 シリーズ (例:qwen3.5-plus、qwen3.6-plus、qwen3.7-plus):返される座標は、[0, 999] の範囲に正規化された相対値です。検出フレームを描画するには、qwen3_vl_2d.py (2D 位置特定) または qwen3_vl_3d.zip (3D 位置特定) のコードをご参照ください。

エラーコード

モデルの呼び出しに失敗した場合、エラーメッセージが返されます。エラーの解決方法については、「エラーコード」をご参照ください。