マルチモーダル、画像、動画、音声モデルを使用する際には、通常、ファイル URL を指定する必要があります。この操作を簡略化するため、Alibaba Cloud Model Studio では無料の一時記憶領域を提供しています。ローカルファイルをこの領域にアップロードすると、有効期間が 48 時間の URL を取得できます。
本ドキュメントは、中国 (北京) リージョンのみに適用されます。モデルを利用するには、中国 (北京) リージョンから取得した API キー を使用する必要があります。
制限事項
ファイルとモデルのバインド：ファイルをアップロードする際に、モデル名を指定する必要があります。後続の API 呼び出しで使用するモデルは、このアップロード時に指定した同一のモデルでなければなりません。異なるモデル間ではファイルを共有できません。また、各モデルには固有のファイルサイズ制限があります。この制限を超えると、アップロードは失敗します。
ファイルとアカウントのバインディング: ファイルのアップロードとモデルの呼び出しに使用される API キーは、同じ Alibaba Cloud アカウントに属している必要があります。アップロードされたファイルは、そのアカウントと対応するモデルでのみ使用できます。他の Alibaba Cloud アカウントやモデルと共有することはできません。
有効期間：ファイルをアップロードした後、そのファイルは48 時間有効です。その後は自動的に削除されます。モデル呼び出しは、この有効期間内に完了させる必要があります。
使用制限：ファイルをアップロードした後、そのファイルは照会、変更、ダウンロードできません。モデル呼び出し時のURL パラメーターとしてのみ使用可能です。
レート制限：アップロード認証情報を取得する API は、各 Alibaba Cloud アカウントおよびモデルごとにクエリ/秒 (QPS) 100 回までに制限されています。この制限を超えるリクエストは失敗します。
一時 URL は 48 時間有効で、有効期限が切れた後は使用できません。本番環境では使用しないでください。
アップロード認証情報を取得する API は QPS 100 で制限されており、スケールアウトはサポートされていません。本番環境、高並行シナリオ、ストレステストシナリオでは使用しないでください。
本番環境向けには、長期的なファイル可用性を確保し、レート制限の問題を回避するために、Object Storage Service (OSS) などの安定したストレージサービスをご利用ください。
使い方
ステップ 1: 一時 URL を取得する
方法 1: コードを使用してファイルをアップロードする
本トピックでは、ファイルアップロードを簡略化するための Python および Java のサンプルコードを提供します。モデル名とアップロードするファイルを単に指定するだけで一時的な URL を取得できます。
前提条件
呼び出しを実行する前に、API キーおよび API ホストを取得し、その後 API キーを環境変数として構成する必要があります。
サンプルコード
Python
環境設定
Python 3.8 以降を推奨します。
必要な依存関係パッケージをインストールします。
pip install -U requests入力パラメーター
api_key：Model Studio の API キー。
model_name: ファイルを使用するモデル。例:
qwen-vl-plus。file_path: アップロードするローカルファイルのパス。画像や動画ファイルなど。
import os
import requests
from pathlib import Path
from datetime import datetime, timedelta
def get_upload_policy(api_key, model_name):
"""ファイルアップロード認証情報を取得します。"""
url = "https://dashscope.aliyuncs.com/api/v1/uploads"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
params = {
"action": "getPolicy",
"model": model_name
}
response = requests.get(url, headers=headers, params=params)
if response.status_code != 200:
raise Exception(f"アップロード認証情報の取得に失敗しました：{response.text}")
return response.json()['data']
def upload_file_to_oss(policy_data, file_path):
"""ファイルを一時的な OSS ストレージにアップロードします。"""
file_name = Path(file_path).name
key = f"{policy_data['upload_dir']}/{file_name}"
with open(file_path, 'rb') as file:
files = {
'OSSAccessKeyId': (None, policy_data['oss_access_key_id']),
'Signature': (None, policy_data['signature']),
'policy': (None, policy_data['policy']),
'x-oss-object-acl': (None, policy_data['x_oss_object_acl']),
'x-oss-forbid-overwrite': (None, policy_data['x_oss_forbid_overwrite']),
'key': (None, key),
'success_action_status': (None, '200'),
'file': (file_name, file)
}
response = requests.post(policy_data['upload_host'], files=files)
if response.status_code != 200:
raise Exception(f"ファイルのアップロードに失敗しました：{response.text}")
return f"oss://{key}"
def upload_file_and_get_url(api_key, model_name, file_path):
"""ファイルをアップロードし、URL を取得します。"""
# 1. アップロード認証情報を取得します。アップロード認証情報を取得する API はレート制限が適用されます。制限を超えるとリクエストは失敗します。
policy_data = get_upload_policy(api_key, model_name)
# 2. ファイルを OSS にアップロードします。
oss_url = upload_file_to_oss(policy_data, file_path)
return oss_url
# 例
if __name__ == "__main__":
# 環境変数から API キーを取得するか、コード内で api_key = "your_api_key" と設定します。
api_key = os.getenv("DASHSCOPE_API_KEY")
if not api_key:
raise Exception("DASHSCOPE_API_KEY 環境変数を設定してください。")
# モデル名を設定します。
model_name="qwen-vl-plus"
# アップロードするファイルのパス。
file_path = "/tmp/cat.png" # 実際のファイルパスに置き換えてください。
try:
public_url = upload_file_and_get_url(api_key, model_name, file_path)
expire_time = datetime.now() + timedelta(hours=48)
print(f"ファイルのアップロードに成功しました。有効期間は 48 時間です。有効期限：{expire_time.strftime('%Y-%m-%d %H:%M:%S')}")
print(f"一時的な URL：{public_url}")
print("注意：oss:// プレフィックス付きの一時的な URL を使用する場合、HTTP リクエストヘッダーに X-DashScope-OssResourceResolve: enable パラメーターを追加する必要があります。詳細については、https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call をご参照ください。")
except Exception as e:
print(f"エラー：{str(e)}")サンプル出力
ファイルのアップロードに成功しました。有効期間は 48 時間です。有効期限：2024-07-18 17:36:15
一時的な URL：oss://dashscope-instant/xxx/2024-07-18/xxx/cat.png
注意：oss:// プレフィックス付きの一時的な URL を使用する場合、HTTP リクエストヘッダーに X-DashScope-OssResourceResolve: enable パラメーターを追加する必要があります。詳細については、https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call をご参照ください。一時的な URL を取得した後、呼び出しを行う際に、HTTP リクエストヘッダーに X-DashScope-OssResourceResolve: enable パラメーターを追加する必要があります。詳細については、「HTTP を使用した呼び出し」をご参照ください。
Java
環境設定
JDK 1.8 以降を推奨します。
Maven プロジェクトの
pom.xmlファイルに次の依存関係をインポートします。
<dependencies>
<dependency>
<groupId>org.json</groupId>
<artifactId>json</artifactId>
<version>20230618</version>
</dependency>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
<version>4.5.13</version>
</dependency>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpmime</artifactId>
<version>4.5.13</version>
</dependency>
</dependencies>入力パラメーター
apiKey：Model Studio へのアクセスに使用する API キー。
modelName: ファイルを使用するモデル。例:
qwen-vl-plus。filePath: アップロードするローカルファイルのパス。画像や動画ファイルなど。
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.entity.ContentType;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.HttpStatus;
import org.apache.http.util.EntityUtils;
import org.json.JSONObject;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
public class PublicUrlHandler {
private static final String API_URL = "https://dashscope.aliyuncs.com/api/v1/uploads";
public static JSONObject getUploadPolicy(String apiKey, String modelName) throws IOException {
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
HttpGet httpGet = new HttpGet(API_URL);
httpGet.addHeader("Authorization", "Bearer " + apiKey);
httpGet.addHeader("Content-Type", "application/json");
String query = String.format("action=getPolicy&model=%s", modelName);
httpGet.setURI(httpGet.getURI().resolve(httpGet.getURI() + "?" + query));
try (CloseableHttpResponse response = httpClient.execute(httpGet)) {
if (response.getStatusLine().getStatusCode() != 200) {
throw new IOException("アップロード認証情報の取得に失敗しました： " +
EntityUtils.toString(response.getEntity()));
}
String responseBody = EntityUtils.toString(response.getEntity());
return new JSONObject(responseBody).getJSONObject("data");
}
}
}
public static String uploadFileToOSS(JSONObject policyData, String filePath) throws IOException {
Path path = Paths.get(filePath);
String fileName = path.getFileName().toString();
String key = policyData.getString("upload_dir") + "/" + fileName;
HttpPost httpPost = new HttpPost(policyData.getString("upload_host"));
MultipartEntityBuilder builder = MultipartEntityBuilder.create();
builder.addTextBody("OSSAccessKeyId", policyData.getString("oss_access_key_id"));
builder.addTextBody("Signature", policyData.getString("signature"));
builder.addTextBody("policy", policyData.getString("policy"));
builder.addTextBody("x-oss-object-acl", policyData.getString("x_oss_object_acl"));
builder.addTextBody("x-oss-forbid-overwrite", policyData.getString("x_oss_forbid_overwrite"));
builder.addTextBody("key", key);
builder.addTextBody("success_action_status", "200");
byte[] fileContent = Files.readAllBytes(path);
builder.addBinaryBody("file", fileContent, ContentType.DEFAULT_BINARY, fileName);
httpPost.setEntity(builder.build());
try (CloseableHttpClient httpClient = HttpClients.createDefault();
CloseableHttpResponse response = httpClient.execute(httpPost)) {
if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
throw new IOException("ファイルのアップロードに失敗しました： " +
EntityUtils.toString(response.getEntity()));
}
return "oss://" + key;
}
}
public static String uploadFileAndGetUrl(String apiKey, String modelName, String filePath) throws IOException {
JSONObject policyData = getUploadPolicy(apiKey, modelName);
return uploadFileToOSS(policyData, filePath);
}
public static void main(String[] args) {
// 環境変数から API キーを取得します。
String apiKey = System.getenv("DASHSCOPE_API_KEY");
if (apiKey == null || apiKey.isEmpty()) {
System.err.println("DASHSCOPE_API_KEY 環境変数を設定してください。");
System.exit(1);
}
// モデル名。
String modelName = "qwen-vl-plus";
// 実際のファイルパスに置き換えてください。
String filePath = "src/main/resources/tmp/cat.png";
try {
// ファイルの存在を確認します。
File file = new File(filePath);
if (!file.exists()) {
System.err.println("ファイルが存在しません： " + filePath);
System.exit(1);
}
String publicUrl = uploadFileAndGetUrl(apiKey, modelName, filePath);
LocalDateTime expireTime = LocalDateTime.now().plusHours(48);
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
System.out.println("ファイルのアップロードに成功しました。有効期間は 48 時間です。有効期限： " + expireTime.format(formatter));
System.out.println("一時的な URL： " + publicUrl);
System.out.println("注意：oss:// プレフィックス付きの一時的な URL を使用する場合、HTTP リクエストヘッダーに X-DashScope-OssResourceResolve: enable パラメーターを追加する必要があります。詳細については、https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call をご参照ください。");
} catch (IOException e) {
System.err.println("エラー： " + e.getMessage());
}
}
}サンプル出力
ファイルのアップロードに成功しました。有効期間は 48 時間です。有効期限：2024-07-18 17:36:15
一時的な URL：oss://dashscope-instant/xxx/2024-07-18/xxx/cat.png
注意：oss:// プレフィックス付きの一時的な URL を使用する場合、HTTP リクエストヘッダーに X-DashScope-OssResourceResolve: enable パラメーターを追加する必要があります。詳細については、https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call をご参照ください。一時的な URL を取得した後、呼び出しを行う際に、HTTP リクエストヘッダーに X-DashScope-OssResourceResolve: enable パラメーターを追加する必要があります。詳細については、「HTTP を使用した呼び出し」をご参照ください。
方法 2: コマンドラインインターフェイスを使用してファイルをアップロードする
コマンドラインに慣れている開発者は、DashScope が提供するコマンドラインインターフェイス (CLI) を使用してファイルをアップロードできます。コマンドを実行すると、一時的な URL が取得されます。
前提条件
環境: Python 3.8 以降を推奨します。
API キー：開始する前に、API キーを取得します。
SDK のインストール: DashScope Python SDK のバージョンは
1.24.0以降である必要があります。次のコマンドを実行してインストールまたはアップグレードします:
pip install -U dashscope方法 1: 環境変数を使用する (推奨)
この方法は、API キーがコマンド履歴やスクリプトでプレーンテキストとして公開されるのを防ぐため、より安全です。
前提条件： API キーを環境変数として構成済みである必要があります。
アップロードコマンドを実行します:
dashscope oss.upload --model qwen-vl-plus --file cat.png出力例:
Start oss.upload: model=qwen-vl-plus, file=cat.png, api_key=None
Uploaded oss url: oss://dashscope-instant/xxxx/2025-08-01/xxxx/cat.png一時的な URL を取得した後、呼び出しを行う際には、X-DashScope-OssResourceResolve: enable パラメーターを HTTP リクエストヘッダーに必ず追加する必要があります。 詳細については、「HTTP を使用した呼び出し」をご参照ください。
方法 2: コマンドラインパラメーターを使用して API キーを指定する (一時的な使用)
アップロードコマンドを実行します:
dashscope oss.upload --model qwen-vl-plus --file cat.png --api_key sk-xxxxxxx出力例:
Start oss.upload: model=qwen-vl-plus, file=cat.png, api_key=sk-xxxxxxx
Uploaded oss url: oss://dashscope-instant/xxx/2025-08-01/xxx/cat.png一時的な URL を取得した後、呼び出しを行う際に、HTTP リクエストヘッダーに X-DashScope-OssResourceResolve: enable パラメーターを必ず追加する必要があります。詳細については、「HTTP を使用した呼び出し」をご参照ください。
コマンドラインパラメーターの説明
パラメーター | 必須 | 説明 | 例 |
oss.upload | はい | ファイルアップロード操作を実行するために使用される DashScope サブコマンド。 | oss.upload |
--model | はい | ファイルがどのモデルで使用されるかを指定します。 | qwen-vl-plus |
--file | はい | ローカルファイルのパス。相対パスまたは絶対パスを指定できます。 | cat.png, /data/img.jpg |
--api_key | いいえ | Model Studio の API キー。環境変数が既に構成されている場合は、このパラメーターは不要です。 | sk-xxxx |
ステップ 2：一時的な URL を使用したモデルの呼び出し
制限事項
ファイル形式：一時的な URL は、前述の方法で生成された
oss://プレフィックス付きの URL 文字列である必要があります。URL の有効性：ファイル URL は、ファイルをアップロードした後、48 時間有効です。
モデルの一貫性: 呼び出しに使用するモデルは、ファイルのアップロード時に指定したモデルと同じである必要があります。
アカウントの整合性：モデル呼び出しに使用する API キーは、ファイルアップロードに使用した API キーと同じ Alibaba Cloud アカウントに属している必要があります。
方法 1: HTTP を使用して呼び出す
curl、Postman、その他の HTTP クライアントを使用して API を直接呼び出す場合、次のルールを必ず遵守してください：
一時 URL を使用する場合、リクエストヘッダーに次のパラメーターを必ず追加する必要があります:
X-DashScope-OssResourceResolve: enable。このヘッダーが欠落していると、システムは
oss://リンクを解析できず、リクエストは失敗します。詳細については、エラーコードをご参照ください。
リクエスト例
この例では、qwen-vl-plus を呼び出して画像の内容を識別する方法を示します。
実際の一次 URL で oss://... を置き換えてください。そうしないと、リクエストは失敗します。
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-OssResourceResolve: enable' \
-d '{
"model": "qwen-vl-plus",
"messages": [{
"role": "user",
"content":
[{"type": "text","text": "What is this?"},
{"type": "image_url","image_url": {"url": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"}}]
}]
}'レスポンス例
{
"choices": [
{
"message": {
"content": "これは、芝生の上で走っている白猫の写真です。猫の目は青く、とてもかわいく活気があります。背景はぼかされた自然の風景で、被写体である小さな猫が強調されています。この撮影技法は、浅い被写界深度（または大きな絞り効果）と呼ばれます。これにより、前景の猫はシャープで鮮明になり、背景はぼかされて被写体が強調され、夢のような効果が得られます。全体として、この写真はリラックスしていて心地よく、動物の動きの素晴らしい瞬間を捉えています。",
"role": "assistant"
},
"finish_reason": "stop",
"index": 0,
"logprobs": null
}
],
"object": "chat.completion",
"usage": {
"prompt_tokens": 1253,
"completion_tokens": 104,
"total_tokens": 1357
},
"created": 1739349052,
"system_fingerprint": null,
"model": "qwen-vl-plus",
"id": "chatcmpl-cfc4f2aa-22a8-9a94-8243-44c5bd9899bc"
}
アップロードされたローカル画像の例
方法 2: DashScope SDK を使用して呼び出す
Model Studio の Python または Java SDK を使用します。
URL を直接渡す：SDK を使用してモデルを呼び出す場合、
oss://プレフィックス付きの URL 文字列をファイルパラメーターとして直接渡します。ヘッダーを意識する必要なし：SDK が自動的に必要なリクエストヘッダーを追加します。追加の操作は不要です。
注: すべてのモデルが SDK 呼び出しをサポートしているわけではありません。詳細については、特定のモデルの API リファレンスを参照してください。
OpenAI SDK はサポートされていません。
Python
前提条件
DashScope Python SDK をインストール（1.24.0 以降）します。
サンプルコード
この例では、qwen-vl-plus を呼び出して画像の内容を識別する方法を示します。このコードサンプルは、qwen-vl および omni モデルにのみ適用されます。
リクエスト例
画像パラメーターの oss://... を実際の一次 URL に置き換えてください。そうしないと、リクエストは失敗します。
import os
import dashscope
messages = [
{
"role": "system",
"content": [{"text": "You are a helpful assistant."}]
},
{
"role": "user",
"content": [
{"image": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"},
{"text": "What is this?"}]
}]
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: api_key="sk-xxx"
api_key = os.getenv('DASHSCOPE_API_KEY')
response = dashscope.MultiModalConversation.call(
api_key=api_key,
model='qwen-vl-plus',
messages=messages
)
print(response)
レスポンス例
{
"status_code": 200,
"request_id": "ccd9dcfb-98f0-92bc-xxxxxx",
"code": "",
"message": "",
"output": {
"text": null,
"finish_reason": null,
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"text": "これは、草の上を走る猫の写真です。猫の毛は主に白で、薄茶色の斑点があり、目は青く、とてもかわいく見えます。背景はぼやけた緑の牧草地で、いくつかの木があり、太陽の光が写真全体に暖かい雰囲気を与えています。猫の姿勢は、何かを追いかけているか、単に屋外を楽しんでいるか、素早く動いていることを示しています。全体として、これは活気に満ちた生き生きとした写真です。"
}
]
}
}
]
},
"usage": {
"input_tokens": 1112,
"output_tokens": 91,
"input_tokens_details": {
"text_tokens": 21,
"image_tokens": 1091
},
"prompt_tokens_details": {
"cached_tokens": 0
},
"total_tokens": 1203,
"output_tokens_details": {
"text_tokens": 91
},
"image_tokens": 1091
}
}Java
前提条件
DashScope Java SDK をインストール（2.21.0 以降）します。
サンプルコード
この例では、qwen-vl-plus を呼び出して画像の内容を識別する方法を示します。このコードサンプルは、qwen-vl および omni モデルにのみ適用されます。
リクエスト例
実際の一次 URL で oss://... を置き換えてください。そうしないと、リクエストは失敗します。
import com.alibaba.dashscope.aigc.multimodalconversation.*;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Arrays;
public class MultiModalConversationUsage {
private static final String modelName = "qwen-vl-plus";
// 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: api_key="sk-xxx"
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void simpleMultiModalConversationCall() throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessageItemText systemText = new MultiModalMessageItemText("You are a helpful assistant.");
MultiModalConversationMessage systemMessage = MultiModalConversationMessage.builder()
.role(Role.SYSTEM.getValue()).content(Arrays.asList(systemText)).build();
MultiModalMessageItemImage userImage = new MultiModalMessageItemImage(
"oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png");
MultiModalMessageItemText userText = new MultiModalMessageItemText("What is this?");
MultiModalConversationMessage userMessage =
MultiModalConversationMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(userImage, userText)).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
.model(MultiModalConversationUsage.modelName)
.apiKey(apiKey)
.message(systemMessage)
.vlHighResolutionImages(true)
.vlEnableImageHwOutput(true)
// .incrementalOutput(true)
.message(userMessage).build();
MultiModalConversationResult result = conv.call(param);
System.out.print(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException /*| IOException*/ e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
レスポンス例
{
"requestId": "b6d60f91-4a7f-9257-xxxxxx",
"usage": {
"input_tokens": 1112,
"output_tokens": 91,
"total_tokens": 1203,
"image_tokens": 1091,
"input_tokens_details": {
"text_tokens": 21,
"image_tokens": 1091
},
"output_tokens_details": {
"text_tokens": 91
}
},
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"text": "これは、草の上を走る猫の写真です。猫の毛は主に白で、薄茶色の斑点があり、目は青く、とてもかわいく見えます。背景はぼやけた緑の牧草地で、いくつかの木があり、太陽の光が写真全体に暖かい雰囲気を与えています。猫の姿勢は、何かを追いかけているか、単に屋外を楽しんでいるか、素早く動いていることを示しています。全体として、これは活気に満ちた生き生きとした写真です。"
},
{
"image_hw": [
[
"924",
"924"
]
]
}
]
}
}
]
}
}付録: API リファレンス
一時的な URL の取得の 2 つの方法は、ファイルアップロードを簡略化するために、以下の 3 つのステップを統合しています。各ステップの API リファレンスを以下に示します。
ステップ 1: ファイルアップロード資格情報を取得する
前提条件
API エンドポイント
GET https://dashscope.aliyuncs.com/api/v1/uploadsファイルアップロード資格情報を取得するための API は、Alibaba Cloud アカウントとモデルごとに 100 QPS にレート制限されています。一時ストレージはスケールアウトできません。本番環境や高同時実行シナリオでは、Alibaba Cloud OSS などのストレージサービスを使用してください。
リクエストパラメーター
場所 | フィールド | タイプ | 必須 | 説明 | 値の例 |
ヘッダー | Content-Type | string | はい | リクエストタイプ: application/json。 | application/json |
Authorization | string | はい | Model Studio の API キー（例：Bearer sk-xxx）。 | Bearer sk-xxx | |
Params | action | string | はい | 操作タイプ。このシナリオでは、値は | getPolicy |
model | string | はい | 呼び出すモデルの名前。 | qwen-vl-plus |
レスポンスパラメーター
フィールド | タイプ | 説明 | 値の例 |
request_id | string | リクエストの一意の ID。 | 7574ee8f-...-11c33ab46e51 |
data | object | - | - |
data.policy | string | アップロード資格情報。 | eyJl...1ZSJ9XX0= |
data.signature | string | アップロード資格情報の署名。 | g5K...d40= |
data.upload_dir | string | ファイルをアップロードするためのフォルダー。 | dashscope-instant/xxx/2024-07-18/xxxx |
data.upload_host | string | アップロード用のホストアドレス。 | https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com |
data.expire_in_seconds | string | 資格情報の有効期間 (秒)。 説明 資格情報の有効期限が切れた後、この API 操作を再度呼び出して新しい資格情報を取得する必要があります。 | 300 |
data.max_file_size_mb | string | アップロードできるファイルの最大サイズ (MB)。 この値はアクセスするモデルに関連しています。 | 100 |
data.capacity_limit_mb | string | Alibaba Cloud アカウントの 1 日あたりのアップロード容量制限 (MB)。 | 999999999 |
data.oss_access_key_id | string | アップロードに使用されるアクセスキー。 | LTAxxx |
data.x_oss_object_acl | string | アップロードされたファイルのアクセス権限。値 | private |
data.x_oss_forbid_overwrite | string | 同じ名前のファイルを上書きするかどうかを指定します。値 | true |
リクエスト例
curl --location 'https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model=qwen-vl-plus' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json'Model Studio API キーを環境変数として設定していない場合は、$DASHSCOPE_API_KEY を API キーに置き換えてください。例: --header "Authorization: Bearer sk-xxx"。
レスポンス例
{
"request_id": "52f4383a-c67d-9f8c-xxxxxx",
"data": {
"policy": "eyJl...1ZSJ=",
"signature": "eWy...=",
"upload_dir": "dashscope-instant/xxx/2024-07-18/xxx",
"upload_host": "https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com",
"expire_in_seconds": 300,
"max_file_size_mb": 100,
"capacity_limit_mb": 999999999,
"oss_access_key_id": "LTA...",
"x_oss_object_acl": "private",
"x_oss_forbid_overwrite": "true"
}
}ステップ 2: 一時記憶領域にファイルをアップロードする
前提条件
ファイルアップロード認証情報を取得します。
ファイルアップロード資格情報の有効期限が切れていないことを確認してください。資格情報の有効期限が切れている場合は、ステップ 1 の API を再度呼び出して新しい資格情報を取得してください。
ファイルアップロード資格情報の有効期間を確認するには、ステップ 1 の
data.expire_in_secondsレスポンスパラメーターを表示します。値は秒単位です。
API エンドポイント
POST {data.upload_host}{data.upload_host} をステップ 1 の data.upload_host レスポンスパラメーターの値に置き換えてください。
リクエストパラメーター
場所 | フィールド | タイプ | 必須 | 説明 | 値の例 |
ヘッダー | Content-Type | string | いいえ | フォームは フォームを送信すると、Content-Type は boundary はランダムに生成される文字列であり、指定する必要はありません。SDK を使用してフォームを構築する場合、SDK もこのランダムな値を自動的に生成します。 | multipart/form-data; boundary=9431149156168 |
form-data | OSSAccessKeyId | text | はい | ファイルアップロード資格情報を取得するための API の | LTAm5xxx |
policy | text | はい | ファイルアップロード資格情報を取得するための API の | g5K...d40= | |
Signature | text | はい | ファイルアップロード資格情報を取得するための API の | Sm/tv7DcZuTZftFVvt5yOoSETsc= | |
key | text | はい | ファイルアップロード資格情報を取得するための API の | たとえば、
| |
x-oss-object-acl | text | はい | ファイルアップロード資格情報を取得するための API の | private | |
x-oss-forbid-overwrite | text | はい | ファイルアップロード資格情報を取得するための API の | true | |
success_action_status | text | いいえ | 値は通常 200 です。アップロードが完了すると、API は HTTP ステータスコード 200 を返して操作が成功したことを示します。 | 200 | |
file | text | はい | ファイルまたはテキストコンテンツ。 説明
| たとえば、アップロードするファイル |
レスポンスパラメーター
呼び出しが成功した場合、この API はレスポンスパラメーターを返しません。
リクエスト例
curl --location 'https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com' \
--form 'OSSAccessKeyId="LTAm5xxx"' \
--form 'Signature="Sm/tv7DcZuTZftFVvt5yOoSETsc="' \
--form 'policy="eyJleHBpcmF0aW9 ... ... ... dHJ1ZSJ9XX0="' \
--form 'x-oss-object-acl="private"' \
--form 'x-oss-forbid-overwrite="true"' \
--form 'key="dashscope-instant/xxx/2024-07-18/xxx/cat.png"' \
--form 'success_action_status="200"' \
--form 'file=@"/tmp/cat.png"'ステップ 3: ファイル URL を生成する
ファイル URL は、oss:// と key の値 (ステップ 2 の key リクエストパラメーター) を連結して作成されます。この URL は 48 時間有効です。
oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.pngエラーコード
API 呼び出しが失敗し、エラーメッセージが返された場合、トラブルシューティングについては エラーメッセージ をご参照ください。
この 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 が正しいかどうかを確認してください。 一時ファイル URL を使用する場合は、リクエストヘッダーに |
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. | 呼び出し頻度がレート制限をトリガーしました。 ファイルアップロード資格情報 API は、Alibaba Cloud アカウントとモデルごとに 100 QPS にレート制限されています。スロットリングがトリガーされた場合は、リクエスト頻度を減らすか、OSS などの独自のストレージサービスに移行して制限を回避してください。 |
よくある質問
Q：「oss://」プレフィックスが付いた URL を使用した際にエラーが発生した場合は、どうすればよいですか？
A：以下の手順でトラブルシューティングを行ってください。
リクエストヘッダーを確認する：
Postman や curl などのツールを使用して HTTP 経由で API を直接呼び出す場合、X-DashScope-OssResourceResolve: enableパラメーターをヘッダーに追加する必要があります。このパラメーターがないと、サーバーは内部 OSS プロトコルを認識できません。リクエストヘッダーの構成方法については、「HTTP を使用した呼び出し」をご参照ください。URL の有効性を確認する：
oss://リンクは一時的な URL です。リンクが過去 48 時間以内に生成されたことを確認してください。リンクの有効期限が切れている場合は、ファイルを再度アップロードして新しい URL を取得してください。
Q：ファイルアップロードとモデル呼び出しで使用する API キーを異なるものにできますか？
A：ファイルのストレージおよびアクセス権限は、お客様の Alibaba Cloud アカウントに基づいて管理されます。API キーは、そのアカウントへのアクセス認証情報にすぎません。
したがって、同じ Alibaba Cloud アカウントに属する異なる API キーを使用できます。ただし、アカウントの隔離により、モデル呼び出しはアカウントをまたいでファイルを読み取ることができないため、異なる Alibaba Cloud アカウントの API キーは使用できません。
ファイルアップロードおよびモデル呼び出しで使用する API キーが、同一の Alibaba Cloud アカウントに属していることを確認してください。