Qwen-VL などのマルチモーダルモデルに画像、動画、音声を入力するには、ファイル URL が必要です。パブリック URL をお持ちでない場合、Model Studio は無料の一時ストレージを提供します。ファイルをアップロードすると、 48 時間 有効な oss:// URL を取得できます。
dashscope-intl.aliyuncs.com を dashscope.aliyuncs.com に置き換え、北京リージョンの API キーを使用してください(両リージョンの API キーは異なります。API キー を参照)。仕組み
- ファイルをアップロードし、ターゲットモデルを指定します。API は
oss://URL を返します。 - モデル呼び出しの際にその URL を渡します。一時 URL を使用するには、このステップ 2 を完了する必要があります。スキップするとエラーが発生します。 HTTP 呼び出しの場合は、ヘッダー
X-DashScope-OssResourceResolve: enableを追加します。DashScope SDK では、このヘッダーが自動的に追加されます。
制限
制約 | 詳細 |
|---|---|
ファイルとモデルのバインディング | アップロード時にモデル名を指定します。以降の呼び出しでも同じモデルを使用してください。ファイルはモデル間で共有できません。 |
ファイルサイズの制限 | ファイルサイズは 1 GB を超えないようにし、選択したモデルの個別の制限にも準拠してください。 |
ファイルとアカウントのバインディング | アップロードとモデルの呼び出しには、同じ Alibaba Cloud アカウントの API キーを使用してください。ファイルはアカウント間で共有できません。 |
48 時間の有効期限 | ファイルは 48 時間後に自動的に削除されます。この期間内にモデルの呼び出しを完了してください。 |
アップロード後の管理なし | ファイルはクエリ、変更、ダウンロードできません。モデルの呼び出しで URL パラメーターとしてのみ使用されます。 |
レート制限 | アップロード認証情報 API は、アカウントとモデルの組み合わせごとに 100 QPS に制限されています。上限を超えるリクエストは失敗します。一時ストレージはスケールアウトをサポートしていません。 |
前提条件
開始する前に:
- 環境変数に設定済みの API キー
- ファイルを使用するモデル名 (例:
qwen3-vl-plus)
ステップ 1: 一時的な URL を取得する
次のいずれかの方法でファイルをアップロードし、一時的な URL を取得します。
- コードを使用したアップロード
- CLI を使用したアップロード
- Python
- Java
- Python 3.9 以降
- 依存関係をインストールしてください。
パラメーター | 説明 | 例 |
|---|---|---|
| Model Studio の API キー |
|
| ファイルを使用するモデル |
|
| ローカルファイルのパス |
|
ステップ2:一時的な URL を使用したモデルの呼び出し
ファイルをアップロードした後、モデルの呼び出しには oss:// URL を使用します。次の2つのルールが適用されます。
- モデルの一貫性: アップロード時に指定したものと同じモデルを使用します。
- アカウントの一貫性: 同じ Alibaba Cloud アカウントの API キーを使用します。
HTTP
HTTP 経由で API を呼び出す場合 (curl、Postman など) 、次のヘッダーを追加してください。
oss:// URL を解決できず、リクエストは失敗します。
リクエスト例
この例では、qwen3-vl-plus を呼び出して、アップロードされた画像を説明させます。
oss://... を実際の一時的な URL に置き換えてください。
DashScope SDK
DashScope SDK は X-DashScope-OssResourceResolve ヘッダーを自動的に処理します。oss:// URL をファイルパラメーターとして直接渡してください。
OpenAI SDK はサポートされていません。すべてのモデルが SDK の呼び出しをサポートしているわけではありません。詳細については、特定のモデルの API リファレンスをご参照ください。
- Python
- Java
2.0.1 以降。この例では、qwen3-vl-plus を呼び出して、アップロードされた画像を説明させます。このコードは qwen-vl および omni モデルに適用できます。
image パラメーターの oss://... を実際の一時的な URL に置き換えてください。
API リファレンス
ステップ 1 のコードサンプルと CLI は、内部で次の 3 つの API を呼び出します。このリファレンスを使用して、アップロードフローを手動で実装できます。
ファイルアップロード認証情報の取得
リクエストパラメーター
Location | Field | Type | Required | Description | Example |
|---|---|---|---|---|---|
Header | Content-Type | string | Yes | リクエストのタイプです。 |
|
Header | Authorization | string | Yes | Model Studio の API キーです。 |
|
Params | action | string | Yes | 操作タイプです。 |
|
Params | model | string | Yes | ターゲットモデル名です。 |
|
レスポンスパラメーター
Field | Type | Description | Example |
|---|---|---|---|
request_id | string | 一意のリクエスト ID です。 |
|
data | object | - | - |
data.policy | string | アップロード認証情報です。 |
|
data.signature | string | 認証情報署名です。 |
|
data.upload_dir | string | アップロードディレクトリのパスです。 |
|
data.upload_host | string | アップロード先の OSS ホストです。 | |
data.expire_in_seconds | number | 認証情報の有効期間 (秒) です。有効期限が切れた場合は、新しい認証情報を取得してください。 |
|
data.max_file_size_mb | number | アップロードできる最大ファイルサイズ (MB) です。モデルによって異なります。 |
|
data.capacity_limit_mb | number | Alibaba Cloud アカウントあたりの 1 日のアップロード容量 (MB) です。 |
|
data.oss_access_key_id | string | アップロード用のアクセスキーです。 |
|
data.x_oss_object_acl | string | アップロードしたファイルのアクセス権限です。 |
|
data.x_oss_forbid_overwrite | string | 同名ファイルの上書きをブロックするかどうかを指定します。 |
|
サンプルリクエスト
API キーが環境変数として設定されていない場合は、$DASHSCOPE_API_KEYをお使いの API キーに置き換えてください:--header "Authorization: Bearer sk-xxx"。
サンプルレスポンス
一時ストレージへのファイルアップロード
{data.upload_host}は、認証情報レスポンスのdata.upload_hostに置き換えてください。
リクエストパラメーター
Location | Field | Type | Required | Description | Example |
|---|---|---|---|---|---|
Header | Content-Type | string | No |
|
|
form-data | OSSAccessKeyId | text | Yes | 認証情報レスポンスの |
|
form-data | policy | text | Yes | 認証情報レスポンスの |
|
form-data | Signature | text | Yes | 認証情報レスポンスの |
|
form-data | key | text | Yes | 認証情報レスポンスの |
|
form-data | x-oss-object-acl | text | Yes | 認証情報レスポンスの |
|
form-data | x-oss-forbid-overwrite | text | Yes | 認証情報レスポンスの |
|
form-data | success_action_status | text | No | 成功時に返される HTTP ステータスコードです。通常は |
|
form-data | file | file | Yes | アップロードするファイルです。1 リクエストあたり 1 ファイルのみです。 |
|
サンプルリクエスト
ファイルURLの構築
oss:// と、アップロードリクエストの key を連結します。この URL は 48 時間有効です。
エラーコード
API 呼び出しが失敗した場合、一般的なトラブルシューティングについてはエラーメッセージをご参照ください。
以下のエラーコードは、一時ファイルのアップロードに固有のものです。
HTTP ステータス | エラーコード | エラーメッセージ | 原因と解決策 |
|---|---|---|---|
400 | invalid_parameter_error | InternalError.Algo.InvalidParameter: The provided URL does not appear to be valid. Ensure it is correctly formatted. | URL が不正な形式です。URL の形式を確認してください。HTTP 経由で |
400 | InvalidParameter.DataInspection | The media format is not supported or incorrect for the data inspection. | リクエストヘッダーに |
403 | AccessDenied | Invalid according to Policy: Policy expired. | アップロード認証情報の有効期限が切れています。認証情報 API を再度呼び出して、新しい認証情報を取得してください。 |
429 | Throttling.RateQuota | Requests rate limit exceeded, please try again later. | リクエストレートが 100 QPS を超えています。リクエスト頻度を減らすか、本番ワークロードの場合はOSSに移行してください。 |
よくある質問
oss:// URL でエラーが返される場合はどうすればよいですか?
次の手順に従ってください:
- リクエストヘッダーを確認してください。 HTTP (curl、Postmanなど) 経由で API を呼び出す場合は、リクエストヘッダーに
X-DashScope-OssResourceResolve: enableを追加してください。このヘッダーがないと、サーバーはoss://プロトコルを解決できません。DashScope SDK はこのヘッダーを自動的に追加します。 - URLの有効性を確認してください。
oss://URL は、アップロードから48時間後に有効期限が切れます。有効期限が切れている場合は、ファイルを再度アップロードして新しい URL を取得してください。