qwencloud-vision

Qwen Vision（画像・動画の理解）

Qwen VL および QVQ モデルを使用して、画像や動画を分析します。 このスキルは qwencloud/qwencloud-ai の一部です。

スキルディレクトリ

このスキルの内部ファイルを使用して、実行や学習を行います。既定のパスで失敗した場合や詳細が必要な場合は、参照ファイルを必要に応じて読み込んでください。

場所	用途
scripts/analyze.py	画像・動画の理解、複数画像、思考モード
scripts/reason.py	視覚的推論（QVQ、思考の連鎖、ストリーミング）
scripts/ocr.py	OCR によるテキスト抽出
scripts/vision_lib.py	共通ヘルパー（base64、アップロード、ストリーミング）
references/execution-guide.md	フォールバック：curl、コード生成
references/curl-examples.md	base64、複数画像、動画、OCR 用の curl
references/visual-reasoning.md	QVQ および思考モードの詳細
references/prompt-guide.md	タスク別のクエリプロンプトのテンプレート、思考モードの選択
references/ocr.md	OCR のパラメーターと例
references/sources.md	公式ドキュメントの URL

セキュリティ

API キーや認証情報を平文で出力しないでください。 常に変数参照を使用してください（シェルでは $QWENCLOUD_API_KEY、Python では os.environ["QWENCLOUD_API_KEY"]）。スクリプトは QWENCLOUD_API_KEY、次に QWEN_API_KEY、次に DASHSCOPE_API_KEY を受け付けます。認証情報の確認や検出は、必ず値を表示せずに行ってください。報告できるのは状態のみです（例：「設定済み」／「未設定」、「有効」／「無効」）。値を表示してはいけません。秘密情報が含まれる可能性のある .env ファイルや設定ファイルの内容を表示してはいけません。

API キーが設定されていない場合、ユーザーに直接キーの提供を求めてはいけません。 代わりに、プレースホルダー（QWENCLOUD_API_KEY=sk-your-key-here）を含む .env ファイルの作成を支援し、QwenCloud Console から取得した実際のキーに置き換えるよう案内してください。ユーザーから明示的に求められた場合にのみ、実際のキーの値を書き込んでください。

キーの互換性

スクリプトは標準の QwenCloud API キー（sk-...）とToken Plan キー（sk-sp-...）の両方に対応しています。Token Plan キーは、対応するマルチモーダルモデル向けに Token Plan エンドポイントへ自動的に振り分けられます。詳しくは Token Plan model catalog を参照してください。CDN にアクセスできない場合は、ローカルのフォールバックを使用してください。

Token Plan では curl を使用せず、必ず同梱の Python スクリプトを使用してください。

Coding Plan キー（同じく sk-sp- プレフィックスですが、Coding Plan サブスクリプションで購入されたもの）は、直接 API 呼び出しには使用できません。スクリプトは起動時にキーの種類を検出し、それに応じて振り分けます。qwencloud-ops-auth がインストールされている場合は、現在のモデル対応状況、エンドポイントのマッピング、エラーの詳細について、その references/codingplan.md を参照してください。

API キーを公開せずに、その種類を検出します。

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qwencloud_lib import detect_api_key_type
print(detect_api_key_type('scripts/qwencloud_lib.py'))
"

出力	意味
token-plan	Token Plan キーが検出されました（sk-sp- プレフィックス）
payg	標準 PAYG キーが検出されました
not-set	環境内に API キーが見つかりません

モデルの選択

🚫 重大 — ユーザーが指定したパラメーターを絶対に上書きしないでください。 ユーザーがプロンプトまたはリクエスト JSON でモデルを明示的に指定した場合は、必ずそのモデルをそのまま使用してください。次のことはしないでください。

• 「より適切」または新しいモデルに置き換える（例：新しいドキュメントで「推奨」されているからといって、ユーザーの qwen3-vl-plus を qwen3.7-plus／qwen3.8-max に差し替える）
• ユーザーが求めていないパラメーターを追加する（enable_thinking、thinking_budget、vl_high_resolution_images、detail）。ただし、ユーザーが json_mode／schema を要求し、その設定を省略した場合、同梱スクリプトでは enable_thinking: false を送信する必要があります
• 明示されたユーザーの選択を「最適化」する

以下の選択ガイドは、ユーザーがモデルを指定していない場合にのみ適用されます。

モデルを選択、推奨、またはデフォルト設定する前に、最新のQwenCloud ビジョンモデルカタログを取得して読んでください。このカタログには、モデル一覧、モデルの基本情報、タスク別の推奨事項、互換性に関する注意事項、デフォルトが記載されています。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

1. ユーザーがモデルを指定している → 必ず指定されたモデルをそのまま使用してください。置き換えたり「最適化」したりしないでください。上記の構造化出力に関する互換性の動作を除き、要求されていないパラメーターを追加しないでください。思考機能専用モデルは、黙って別のモデルに置き換えるのではなく、使用を拒否してください。
2. モデルの選択が要件、シナリオ、または価格に左右される場合は、qwencloud-model-selector スキルを参照してください。
3. 明確なタスクに対して手掛かりがない → モデルカタログに記載されたデフォルトとタスク別の代替モデルを使用してください。専用スクリプトのデフォルトはキーの種類に関係なく適用されます。Token Plan のユーザーは、デフォルトモデルがプランで利用できない場合、カタログから互換性のあるモデルを選択してください。

⚠️ 重要：モデルカタログは特定時点のスナップショットであり、古くなっている可能性があります。モデルの提供状況は頻繁に変わります。モデルを決定する前に、最新かつ正式なカタログとして、必ず公式モデル一覧を確認してください。

モデルの詳細：特定のモデルについて詳しく知りたい場合は、詳細ページを案内してください：https://www.qwencloud.com/models/<model-name>（<model-name> を正確なモデル ID に置き換えます。例：qwen3.6-plus → https://www.qwencloud.com/models/qwen3.6-plus）。URL 内のモデル名を変更したり、推測したりすることは絶対にしないでください。

動的なモデル照会：qwencloud-model-selector スキルまたは QwenCloud CLI（qwencloud models info <model>）が利用可能な場合は、リアルタイムのモデルデータを使用してください。CLI の使用には認証が必要です。ログイン手順については、qwencloud-usage スキルを参照してください。

実行

前提条件

• API キー：QWENCLOUD_API_KEY、QWEN_API_KEY、次に DASHSCOPE_API_KEY の順に、平文を表示しない方法のみで確認してください（例：シェルで [ -n "$QWENCLOUD_API_KEY" ] を実行し、結果は「設定済み」または「未設定」とだけ報告し、キーの値は決して表示しないでください）。未設定の場合、利用可能であれば * * qwencloud-ops-auth* スキルを実行してください。利用できない場合は、ユーザーにQwenCloud Consoleからキーを取得し、.env ファイル（プロジェクトルートまたは現在のディレクトリで echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env を実行）または環境変数を使って設定するよう案内してください。スクリプトは、現在の作業ディレクトリとプロジェクトルートで .env を検索します。スキルは個別にインストールされている場合があります。qwencloud-ops-auth があると決めつけないでください。 注：スクリプトは、エクスポート済みの環境変数に加えて、現在のディレクトリとプロジェクトルートの .env を自動的に読み込みます。シェルで $QWENCLOUD_API_KEY を確認して「未設定」と表示されても、スクリプトが失敗するとは限りません。.env からキーを見つける場合があります。シェルでの確認結果は参考情報としてのみ扱ってください。キーがどこにも見つからない場合は明確なエラーを出して終了するため、スクリプトを実行することが最終的な確認方法です。
• Python 3.9 以降（標準ライブラリのみ、pip install は不要）

環境の確認

初回実行の前に、Python が利用可能であることを確認します。

python3 --version  # must be 3.9+

python3 が利用できない、またはバージョンが 3.9 未満の場合、PAYG では **Path 2（curl）**を使用できます。Token Plan では、Python 3.9 以上をインストールする必要があります。

デフォルト：スクリプトを実行

スクリプトのパス：スクリプトは、このスキルのディレクトリ（このスキルの SKILL.md があるディレクトリ）内の scripts/ サブディレクトリにあります。必ず最初にこのスキルのインストールディレクトリを特定し、その後は常にスクリプトの実行に完全な絶対パスを使用してください。 スクリプトが現在の作業ディレクトリにあると決めつけないでください。実行前に cd でディレクトリを切り替えないでください。共有インフラストラクチャは scripts/vision_lib.py にあります。

実行上の注意：すべてのスクリプトはフォアグラウンドで実行し、標準出力を待ちます。バックグラウンドでは実行しないでください。

確認方法：まず python3 <this-skill-dir>/scripts/analyze.py --help（または reason.py、ocr.py）を実行して、使用可能な引数をすべて確認します。

スクリプト	目的	デフォルトモデル
scripts/analyze.py	画像の理解、複数画像、動画、思考モード、高解像度	上記のモデルカタログから現在のデフォルトを確認してください
scripts/reason.py	思考の連鎖による視覚的推論、動画の推論（常にストリーミング）	上記のモデルカタログから現在のデフォルトを確認してください
scripts/ocr.py	ドキュメント、レシート、表からの OCR テキスト抽出	上記のモデルカタログから現在のデフォルトを確認してください

入力タイプのフィールド（--request JSON では、次のいずれか 1 つを正確に使用します）：

フィールド	用途	例
"image"	単一の画像（URL またはローカルパス）	"image": "photo.jpg"
"images"	複数画像の比較（配列）	"images": ["a.jpg", "b.jpg"]
"video"	動画ファイル（URL またはローカルパス）	"video": "clip.mp4"
"video_frames"	フレーム配列としての動画	"video_frames": ["f1.jpg", "f2.jpg"]

⚠️ よくある間違い：動画ファイルに "image" を使用しないでください。代わりに "video" を使用します。

# Image analysis
python3 <this-skill-dir>/scripts/analyze.py \
  --request '{"prompt":"What is in this image?","image":"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"}' \
  --output output/qwencloud-vision/result.json --print-response

# Video analysis (local file — add --upload-files for files >= 7 MB)
python3 <this-skill-dir>/scripts/analyze.py \
  --request '{"prompt":"Describe what happens in this video","video":"clip.mp4"}' \
  --upload-files --print-response

python3 <this-skill-dir>/scripts/reason.py \
  --request '{"prompt":"Solve this math problem step by step","image":"problem.png"}' \
  --print-response

python3 <this-skill-dir>/scripts/ocr.py \
  --request '{"image":"invoice.jpg"}' \
  --print-response

引数	説明
--request '{...}'	JSON リクエスト本文
--file path.json	ファイルからリクエストを読み込みます
--output path	レスポンス JSON を指定したパスに保存します
--print-response	レスポンスを標準出力に表示します
--stream	ストリーミングを有効にします（thinking/QVQ では自動）
--upload-files	ローカルファイルを一時ストレージにアップロードします（7 MB 超のファイル用）
--schema path.json	構造化抽出用の JSON Schema

結果の確認

• 終了コードが 0 で、出力に choices フィールドを含む有効な JSON がある → 成功
• 終了コードが 0 以外、HTTP エラー、空のレスポンス、または "code"／"message" エラーを含む JSON → 失敗
• 実行後の確認：--output を使用した場合は、レスポンス JSON ファイルが存在し、期待される内容が含まれていることを確認します
• 必須 — stderr シグナルの確認：結果を確認した後、コマンドの stderr 出力に [ACTION_REQUIRED] または [UPDATE_AVAILABLE] がないか調べます。いずれかのシグナルがある場合は、ユーザーに応答する前に、以下の更新チェックの指示に必ず従ってください。

失敗した場合

スクリプトが失敗した場合は、エラー出力を以下の診断表と照合して、解決方法を確認してください。一致する項目がない場合は、execution-guide.md を読み、別の方法（curl コマンド（Path 2）、コード生成（Path 3）、自律的な解決（Path 5））を確認してください。

Python がまったく利用できない場合 → PAYG では Path 2（curl）を利用できます。Token Plan では Python 3.9 以降をインストールする必要があります。

エラーパターン	診断	解決方法
command not found: python3	Python が PATH にありません	python または py -3 を試してください。見つからない場合は Python 3.9 以降をインストールしてください
Python 3.9+ required	スクリプトのバージョンチェックに失敗しました	Python を 3.9 以降にアップグレードしてください
SyntaxError near type hints	Python が 3.9 未満です	Python を 3.9 以降にアップグレードしてください
QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY not found	API キーがありません	QwenCloud Console からキーを取得し、.env に追加してください：echo 'QWENCLOUD_API_KEY=sk-...' >> .env。または、利用可能な場合は qwencloud-ops-auth を実行してください
HTTP 401	キーが無効、または一致していません	qwencloud-ops-auth を実行し（平文以外のチェックのみ）、キーが有効であることを確認してください
SSL: CERTIFICATE_VERIFY_FAILED	SSL 証明書の問題（プロキシ／社内ネットワーク）	macOS：Install Certificates.command を実行してください。それ以外の場合は SSL_CERT_FILE 環境変数を設定してください
URLError / ConnectionError	ネットワークに接続できません	インターネット接続を確認してください。プロキシ経由の場合は HTTPS_PROXY を設定してください
HTTP 429	レート制限されています	待ってから、バックオフを適用して再試行してください
HTTP 5xx	サーバーエラー	バックオフを適用して再試行してください
PermissionError	出力を書き込めません	--output を使って、書き込み可能なディレクトリを指定してください

ファイル入力

API は HTTP/HTTPS URL、Base64 データ URI、oss:// URL を受け付けます。ローカルファイルパスは直接サポートされていませんが、スクリプトが自動的に変換します。ローカルパスをそのまま渡してください。手動でアップロードする必要はありません。

大容量ファイルのルール：ローカルファイルが 7 MB 以上の場合は、必ず --upload-files を追加してください。 Base64 エンコードによりサイズが約 33％増加し、API の 10 MB 制限を超えてしまいます。小さなファイル（7 MB 未満の短い動画クリップを含む）には、デフォルトの Base64 経路を使用できます。

方法	使用するタイミング	方法
オンライン URL	ファイルがすでにホストされている場合	URL をそのまま渡します — 大容量ファイルではこちらを推奨
Base64（デフォルト）	7 MB 未満のローカルファイル（画像または短い動画クリップ）	スクリプトが自動的に data: URI に変換します
一時アップロード	7 MB 以上のローカルファイル	--upload-files フラグを追加 → DashScope の一時ストレージにアップロードします（oss:// URL、TTL は 48 時間）

本番環境： デフォルトの一時ストレージには TTL 48 時間 と アップロード上限 100 QPS が設定されており、本番環境、高い同時実行数、負荷テストには適していません。独自の OSS バケットを使用するには、.env で QWEN_TMP_OSS_BUCKET と QWEN_TMP_OSS_REGION を設定し、pip install alibabacloud-oss-v2 をインストールして、QWEN_TMP_OSS_AK_ID / QWEN_TMP_OSS_AK_SECRET または標準の OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET で認証情報を指定してください。最小権限（対象バケットのみの oss:PutObject と oss:GetObject）を持つ RAM ユーザーを使用してください。ビジョンスクリプトでアップロードを実行するには、引き続き --upload-files フラグが必要です。qwencloud-ops-auth がインストールされている場合は、詳細なセットアップガイドについて、その references/custom-oss.md を参照してください。

他のスキルからの入力

入力ファイルが別のスキルの出力（例：image-gen、video-gen）である場合：

• URL をそのまま渡してください（例："image": "<image_url from image-gen>"） — URL を先にダウンロードしないでください
• ダウンロードしてローカルパスとして渡し直すと、帯域幅が無駄になり、不要な Base64 エンコードまたは OSS アップロードが発生します
• すべての URL 形式に対応しています：https://、oss://、data:

思考モード

現在の思考モードのデフォルト設定とモデルの互換性については、上記のビジョンモデルカタログを参照してください。ユーザーから変更を明示的に求められない限り、enable_thinking は設定しないでください。「タスクが複雑そうだから」という理由で有効にしたり、「タスクが簡単そうだから」という理由で無効にしたりしないでください。唯一の互換性に関する例外は構造化出力です。json_mode と schema には非思考モードが必要なため、同梱のスクリプトは設定が省略された場合に自動的に enable_thinking: false を送信し、明示的な true は拒否します。思考専用モデルは構造化出力には使用できません。

詳細については、visual-reasoning.md を参照してください。

OCR

現在の OCR のデフォルト設定、代替手段、モデルの機能については、上記のビジョンモデルカタログを参照してください。パラメーターと例については、ocr.md を参照してください。

入力制限

画像： BMP/JPEG/PNG/TIFF/WEBP/HEIC。辺の最小サイズは 10px、アスペクト比は 200:1 以下です。モデル固有のサイズ制限については、上記のモデルカタログを確認してください。

動画： MP4/AVI/MKV/MOV/FLV/WMV。モデル固有の時間とサイズの制限については、上記のモデルカタログを確認してください。fps の範囲は [0.1, 10]、デフォルトは 2.0 です。

エラー処理

HTTP	意味	対応
401	API キーが無効、または設定されていません	利用可能な場合は qwencloud-ops-auth を実行します。利用できない場合は、ユーザーにキーの設定を依頼します（平文でないことのみ確認）
400	不正なリクエスト（形式が無効）	メッセージの形式と画像の URL／形式を確認します
429	レート制限	指数バックオフで再試行します
5xx	サーバーエラー	指数バックオフで再試行します

利用状況と請求：qwencloud-usage スキルを使用すると、利用状況、無料枠の上限、請求を直接確認できます。または、ユーザーは QwenCloud コンソールにアクセスできます： 利用状況分析 | 従量課金制の請求 | Coding Plan の請求

利用状況、請求、コンソールの URL を決して捏造、推測、作成しないでください。 このスキルに記載された正確なリンクのみを提示してください。ここに記載されていない URL は作成しないでください。

出力先

現在の作業ディレクトリを優先します。デフォルトのサブディレクトリ：./output/qwencloud-vision/。

書き込み禁止：このスキルのインストールディレクトリや、skills/ 階層内に出力ファイルを決して書き込まないでください。生成したすべてのコンテンツは、現在の作業ディレクトリ内の output/、またはユーザー指定のパスに保存してください。

Token Plan のサポート

Token Plan キー（sk-sp-...）は、ビジョン機能を備えたマルチモーダルモデルでサポートされています。

サポート対象のビジョンモデル

最新の Token Plan モデルカタログを取得して読み込み、一覧に正確に記載されているビジョン対応モデルを使用してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

これらのモデルは、マルチモーダルメッセージ形式（image_url コンテンツタイプ）で OpenAI 互換のチャット API を使用します。

デフォルト

モデルが指定されていない場合、各スクリプトはキーの種類にかかわらず、設定済みのデフォルトを使用します。現在の互換性を確認するには、ビジョンカタログと Token Plan カタログを確認してください。明示的に指定されたリクエストモデルが常に優先されます。

Token Plan ではサポートされないモデル

Token Plan モデルカタログにビジョン対応として記載されていないモデルには、PAYG キーが必要です。互換性のある代替モデルをビジョンカタログから提案できるのは、ユーザーが明示的に同意した場合のみです。キーの種類の制限を理由に、ユーザー指定のモデルを黙って切り替えてはいけません。選択肢を提示し、ユーザーに選んでもらってください。

必須ヘッダー

User-Agent: qwencloud-skills は自動的に追加されます。

更新の確認（実行後に必須）

スクリプトの実行後、標準エラー出力にアクションを示すシグナルがないか確認してください。スクリプトは更新状況を自動検出し、構造化されたシグナルを出力します。これらのシグナルには必ず対応してください。このセクションは、ユーザーが明示的に更新確認を依頼した場合にも適用されます。

シグナル：[ACTION_REQUIRED] qwencloud-update-check skill is not installed

標準エラー出力にこのシグナルが含まれている場合は、以下の選択肢をユーザーに提示し、続行する前に回答を待ってください。黙ってスキップしてはいけません。

更新確認スキルがインストールされていません。このスキルにより、qwencloud/qwencloud-ai の新機能やバグ修正に関する情報を受け取れます。

1. 今すぐインストール — インストールコマンドを実行します
2. 今回はスキップ — 今回は何もしません
3. 今後通知しない — この確認を今後表示しないようにします

ユーザーの回答後：

• ユーザーが 1 を選択 → npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y を実行し、続けて python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行します
• ユーザーが 2 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行し、その後通常どおり続行します
• ユーザーが 3 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --never-install を実行し、その後通常どおり続行します

シグナル：[UPDATE_AVAILABLE]

標準エラー出力にこのシグナルが含まれている場合は、バージョン情報と標準エラー出力に表示された更新コマンドを含む、簡潔な更新通知を応答に追記してください。

stderr にシグナルがない場合

stderr に [ACTION_REQUIRED] も [UPDATE_AVAILABLE] も含まれていない場合、対応は不要です。スキルはインストール済みで最新の状態です（または24時間以内のキャッシュが使用されています）。

ユーザーから明示的な依頼があった場合

ユーザーから更新の確認を明示的に依頼された場合（例：「更新を確認して」「バージョンを確認して」）：

1. 隣接するスキルディレクトリで qwencloud-update-check/SKILL.md を探します。
2. 見つかった場合は、python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。
3. 見つからない場合は、上記のインストール方法を提示します。

参考資料

• execution-guide.md — 代替手段（curl、コード生成、自律実行）
• curl-examples.md — Curl のテンプレート（base64、複数画像、動画、OCR）
• api-guide.md — API の補足ガイド
• visual-reasoning.md — QVQ の視覚的推論ガイド
• ocr.md — Qwen-VL-OCR のテキスト抽出ガイド
• sources.md — 公式ドキュメントの URL