Skip to main content

ローカルファイルのアップロードと一時的な URL の取得

Qwen-VL などのマルチモーダルモデルに画像、動画、音声を入力するには、ファイル URL が必要です。パブリック URL をお持ちでない場合、Model Studio は無料の一時ストレージを提供します。ファイルをアップロードすると、 48 時間 有効な oss:// URL を取得できます。

一時的な URL は、開発とテスト専用です。本番、高同時実行シナリオ、ストレステストには使用しないでください。本番ワークロードでは、長期的な可用性を確保し、レート制限を回避するため、Object Storage Service (OSS) を使用してください。
この機能は、シンガポールおよびChina (Beijing) リージョンで利用可能です。本ドキュメントのコード例は、デフォルトでシンガポールリージョンを使用します。北京リージョンを使用する場合は、例内のコメントに従ってリクエスト URL の dashscope-intl.aliyuncs.com を dashscope.aliyuncs.com に置き換え、北京リージョンの API キーを使用してください(両リージョンの API キーは異なります。API キー を参照)。

仕組み

  1. ファイルをアップロードし、ターゲットモデルを指定します。API は oss:// URL を返します。
  2. モデル呼び出しの際にその 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 以降
  • 依存関係をインストールしてください。
pip install -U requests
パラメーター

パラメーター

説明

例

api_key

Model Studio の API キー

DASHSCOPE_API_KEY 環境変数から読み取ります

model_name

ファイルを使用するモデル

qwen3-vl-plus

file_path

ローカルファイルのパス

/tmp/cat.png

サンプルコード
import os
import requests
from pathlib import Path
from datetime import datetime, timedelta

def get_upload_policy(api_key, model_name):
    """ファイルアップロード用の認証情報を取得します。"""
    # シンガポールと北京リージョンの API キーは異なります。対応するリージョンのキーを使用してください。
    # 以下の URL はシンガポールリージョン用です。北京リージョンの場合は次に置き換えてください: https://dashscope.aliyuncs.com/api/v1/uploads
    url = "https://dashscope-intl.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"Failed to get upload policy: {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"Failed to upload file: {response.text}")

    return f"oss://{key}"

def upload_file_and_get_url(api_key, model_name, file_path):
    """ファイルをアップロードして URL を取得します。"""
    # 1. アップロード認証情報を取得します (100 QPS のレート制限があります)
    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 = os.getenv("DASHSCOPE_API_KEY")
    if not api_key:
        raise Exception("Set the DASHSCOPE_API_KEY environment variable.")

    # モデル名を設定します
    model_name="qwen3-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"File uploaded successfully. URL valid for 48 hours.")
        print(f"Expiration time: {expire_time.strftime('%Y-%m-%d %H:%M:%S')}")
        print(f"Temporary URL: {public_url}")
        print("Note: When you use a temporary URL with the oss:// prefix, you must add the X-DashScope-OssResourceResolve: enable parameter to the HTTP request header. For more information, see https://www.alibabacloud.com/help/model-studio/get-temporary-file-url#http-call")

    except Exception as e:
        print(f"Error: {str(e)}")
出力例
File uploaded successfully. URL valid for 48 hours.
有効期限:2024-07-18 17:36:15
Temporary URL: oss://dashscope-instant/xxx/2024-07-18/xxx/cat.png
Note: When you use a temporary URL with the oss:// prefix, you must add the X-DashScope-OssResourceResolve: enable parameter to the HTTP request header. For more information, see https://www.alibabacloud.com/help/model-studio/get-temporary-file-url#http-call
一時的な URL を取得した後、呼び出しを行う際には、HTTP リクエストに X-DashScope-OssResourceResolve: enable ヘッダーを追加してください。詳細については、「HTTP を使用した呼び出し」をご参照ください。

ステップ2:一時的な URL を使用したモデルの呼び出し

ファイルをアップロードした後、モデルの呼び出しには oss:// URL を使用します。次の2つのルールが適用されます。
  • モデルの一貫性: アップロード時に指定したものと同じモデルを使用します。
  • アカウントの一貫性: 同じ Alibaba Cloud アカウントの API キーを使用します。
次のいずれかの方法を選択してください。

HTTP

HTTP 経由で API を呼び出す場合 (curl、Postman など) 、次のヘッダーを追加してください。
X-DashScope-OssResourceResolve: enable
このヘッダーがない場合、API は oss:// URL を解決できず、リクエストは失敗します。 リクエスト例 この例では、qwen3-vl-plus を呼び出して、アップロードされた画像を説明させます。
oss://... を実際の一時的な URL に置き換えてください。
# 以下の URL はシンガポールリージョン用です。北京リージョンの場合は次に置き換えてください: https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
curl -X POST https://dashscope-intl.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": "qwen3-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": "This is a picture of a white cat running on the grass. The cat has blue eyes and looks very cute and lively. The background is a blurred natural landscape, which emphasizes the subject: the small cat dashing forward. This photographic technique is called shallow depth of field (or a large aperture effect). It makes the cat in the foreground sharp and clear while blurring the background to highlight the subject and create a dreamlike effect. Overall, this photo feels relaxed and pleasant, and it captures a great moment of the animal's behavior.",
        "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": "qwen3-vl-plus",
  "id": "chatcmpl-cfc4f2aa-22a8-9a94-8243-44c5bd9899bc"
}

DashScope SDK

DashScope SDK は X-DashScope-OssResourceResolve ヘッダーを自動的に処理します。oss:// URL をファイルパラメーターとして直接渡してください。
OpenAI SDK はサポートされていません。すべてのモデルが SDK の呼び出しをサポートしているわけではありません。詳細については、特定のモデルの API リファレンスをご参照ください。
  • Python
  • Java
前提条件: DashScope Python SDK 2.0.1 以降。この例では、qwen3-vl-plus を呼び出して、アップロードされた画像を説明させます。このコードは qwen-vl および omni モデルに適用できます。
image パラメーターの oss://... を実際の一時的な URL に置き換えてください。
import os
import dashscope

# シンガポールと北京リージョンの API キーは異なります。対応するリージョンのキーを使用してください。
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: api_key="sk-xxx"
client = dashscope.Client(api_key=os.getenv('DASHSCOPE_API_KEY'))

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?"}]
    }]

response = client.multimodal.chat.create(
    model='qwen3-vl-plus',
    messages=messages
)

print(response.output_text)
レスポンス例
{
    "request_id": "ccd9dcfb-98f0-92bc-xxxxxx",
    "choices": [
        {
            "index": 0,
            "finish_reason": "stop",
            "message": {
                "role": "assistant",
                "content": "This is a photo of a cat running on the grass. The cat's fur is mainly white with light brown spots, and its eyes are blue, making it look very cute. The background is a blurry green meadow with some trees, and the sunlight adds a warm feeling to the whole picture. The cat's posture shows that it is moving quickly, possibly chasing something or just enjoying the outdoors. Overall, this is a vibrant and lively picture."
            }
        }
    ],
    "usage": {
        "input_tokens": 1112,
        "output_tokens": 91,
        "total_tokens": 1203,
        "input_tokens_details": {
            "text_tokens": 21,
            "image_tokens": 1091
        },
        "output_tokens_details": {
            "text_tokens": 91
        }
    }
}

API リファレンス

ステップ 1 のコードサンプルと CLI は、内部で次の 3 つの API を呼び出します。このリファレンスを使用して、アップロードフローを手動で実装できます。

ファイルアップロード認証情報の取得

Singapore: GET https://dashscope-intl.aliyuncs.com/api/v1/uploads
Beijing: GET https://dashscope.aliyuncs.com/api/v1/uploads
認証情報 API は、アカウントごと、モデルごとに 100 QPS のレート制限があります。一時ストレージはスケールアウトできません。本番環境または高同時実行性ワークロードでは、Alibaba Cloud OSS を使用してください。

リクエストパラメーター

Location

Field

Type

Required

Description

Example

Header

Content-Type

string

Yes

リクエストのタイプです。

application/json

Header

Authorization

string

Yes

Model Studio の API キーです。

Bearer sk-xxx

Params

action

string

Yes

操作タイプです。 getPolicy に設定します。

getPolicy

Params

model

string

Yes

ターゲットモデル名です。

qwen3-vl-plus

レスポンスパラメーター

Field

Type

Description

Example

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

アップロード先の OSS ホストです。

https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com

data.expire_in_seconds

number

認証情報の有効期間 (秒) です。有効期限が切れた場合は、新しい認証情報を取得してください。

300

data.max_file_size_mb

number

アップロードできる最大ファイルサイズ (MB) です。モデルによって異なります。

100

data.capacity_limit_mb

number

Alibaba Cloud アカウントあたりの 1 日のアップロード容量 (MB) です。

999999999

data.oss_access_key_id

string

アップロード用のアクセスキーです。

LTAxxx

data.x_oss_object_acl

string

アップロードしたファイルのアクセス権限です。 private は、ファイルが非公開であることを示します。

private

data.x_oss_forbid_overwrite

string

同名ファイルの上書きをブロックするかどうかを指定します。 true は、上書きがブロックされることを示します。

true

サンプルリクエスト

# 以下の URL はシンガポールリージョン用です。北京リージョンの場合は次に置き換えてください: https://dashscope.aliyuncs.com/api/v1/uploads
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/uploads?action=getPolicy&model=qwen3-vl-plus' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json'
API キーが環境変数として設定されていない場合は、$DASHSCOPE_API_KEY をお使いの API キーに置き換えてください: --header "Authorization: Bearer sk-xxx"。

サンプルレスポンス

{
    "request_id": "52f4383a-c67d-9f8c-xxxxxx",
    "data": {
        "policy": "eyJl...1ZSJ=",
        "signature": "YOUR_SIGNATURE",
        "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"
    }
}

一時ストレージへのファイルアップロード

POST {data.upload_host}
{data.upload_host} は、認証情報レスポンスの data.upload_host に置き換えてください。

リクエストパラメーター

Location

Field

Type

Required

Description

Example

Header

Content-Type

string

No

multipart/form-data としてフォームを送信します。boundary は HTTP クライアントによって自動的に生成されます。

multipart/form-data; boundary=9431149156168

form-data

OSSAccessKeyId

text

Yes

認証情報レスポンスの data.oss_access_key_id です。

LTAm5xxx

form-data

policy

text

Yes

認証情報レスポンスの data.policy です。

eyJl...1ZSJ9XX0=

form-data

Signature

text

Yes

認証情報レスポンスの data.signature です。

Sm/tv7DcZuTZftFVvt5yOoSETsc=

form-data

key

text

Yes

認証情報レスポンスの data.upload_dir に /<filename> を付与した値です。

dashscope-instant/xxx/2024-07-18/xxx/cat.png

form-data

x-oss-object-acl

text

Yes

認証情報レスポンスの data.x_oss_object_acl です。

private

form-data

x-oss-forbid-overwrite

text

Yes

認証情報レスポンスの data.x_oss_forbid_overwrite です。

true

form-data

success_action_status

text

No

成功時に返される HTTP ステータスコードです。通常は 200 です。

200

form-data

file

file

Yes

アップロードするファイルです。1 リクエストあたり 1 ファイルのみです。 file フィールドは、フォームフィールドの最後に配置する必要があります。

file=@"/tmp/cat.png"

成功すると、API は HTTP 200 を返しますが、レスポンスボディはありません。

サンプルリクエスト

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"'

ファイルURLの構築

oss:// と、アップロードリクエストの key を連結します。この URL は 48 時間有効です。
oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png

エラーコード

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 経由でoss:// URL を使用する場合は、X-DashScope-OssResourceResolve: enable ヘッダーを追加してください。

400

InvalidParameter.DataInspection

The media format is not supported or incorrect for the data inspection.

リクエストヘッダーに X-DashScope-OssResourceResolve: enable が含まれていない、またはファイル形式がモデルでサポートされていません。エラーメッセージをご参照ください。

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 でエラーが返される場合はどうすればよいですか?

次の手順に従ってください:
  1. リクエストヘッダーを確認してください。 HTTP (curl、Postmanなど) 経由で API を呼び出す場合は、リクエストヘッダーに X-DashScope-OssResourceResolve: enable を追加してください。このヘッダーがないと、サーバーは oss:// プロトコルを解決できません。DashScope SDK はこのヘッダーを自動的に追加します。
  2. URLの有効性を確認してください。 oss:// URL は、アップロードから48時間後に有効期限が切れます。有効期限が切れている場合は、ファイルを再度アップロードして新しい URL を取得してください。

ファイルのアップロードとモデルの呼び出しで異なる API キーを使用できますか?

はい、両方の API キーが同じ Alibaba Cloud アカウントに属している場合に限り使用できます。ファイルアクセスは API キーレベルではなく、アカウントレベルで管理されます。 異なる Alibaba Cloud アカウントの API キーでは、相互にアップロードされたファイルへアクセスできません。