Cara mengunggah file lokal ke ruang penyimpanan sementara dan mendapatkan URL file - Alibaba Cloud Model Studio

Saat menggunakan model multimodal seperti gambar, video, atau audio, Anda sering perlu menyediakan URL file. Untuk mempermudah hal ini, Alibaba Cloud Model Studio menyediakan ruang penyimpanan sementara gratis. Unggah file lokal ke ruang tersebut dan dapatkan URL yang berlaku selama 48 jam.

Penting

Dokumen ini hanya berlaku untuk wilayah China (Beijing). Untuk menggunakan model-model tersebut, Anda harus menggunakan API key dari wilayah China (Beijing).

Keterbatasan

Pengikatan file-model: Anda harus menentukan nama model saat mengunggah file. Model ini harus sama dengan yang digunakan dalam panggilan berikutnya karena model yang berbeda tidak dapat berbagi file. Selain itu, setiap model memiliki batas ukuran file tertentu. Jika melebihi batas ini, pengunggahan akan gagal.
Pengikatan File-Akun: Kunci API yang digunakan untuk unggahan file dan pemanggilan model harus milik Akun Alibaba Cloud yang sama. File yang diunggah hanya dapat digunakan oleh akun tersebut dan model terkaitnya. File tersebut tidak dapat dibagikan dengan akun Alibaba Cloud lainnya atau model lainnya.
Periode validitas: Setelah file diunggah, file tersebut berlaku selama 48 jam, setelah itu akan dihapus secara otomatis. Pastikan Anda menyelesaikan panggilan model dalam periode validitas ini.
Batasan penggunaan: Setelah file diunggah, file tersebut tidak dapat diquery, dimodifikasi, atau diunduh. File tersebut hanya dapat digunakan sebagai parameter URL dalam panggilan model.
Pembatasan laju: API untuk mendapatkan unggah kredensial dibatasi hingga 100 permintaan per detik (QPS) untuk setiap Akun Alibaba Cloud dan model. Permintaan yang melebihi batas ini akan gagal.

Penting

URL sementara valid selama 48 jam dan tidak dapat digunakan setelah kedaluwarsa. Jangan gunakan dalam lingkungan produksi.
API untuk mendapatkan unggah kredensial dibatasi hingga 100 QPS dan tidak mendukung skala keluar. Jangan menggunakannya di lingkungan produksi, skenario konkurensi tinggi, atau skenario uji stres.
Untuk lingkungan produksi, gunakan layanan penyimpanan yang stabil seperti Object Storage Service (OSS) untuk memastikan ketersediaan file jangka panjang dan menghindari masalah pembatasan laju.

Cara menggunakan

Dapatkan URL file: Pertama, ikuti petunjuk di Langkah 1 untuk mengunggah file, seperti gambar, video, atau file audio, dan dapatkan URL sementara yang diawali dengan oss://.
Panggil model: Anda harus mengikuti petunjuk di Langkah 2 untuk menggunakan URL sementara tersebut dalam panggilan. Jangan lewatkan langkah ini. Jika tidak, API akan mengembalikan error.

Langkah 1: Dapatkan URL sementara

Metode 1: Unggah file menggunakan kode

Topik ini menyediakan contoh kode Python dan Java untuk menyederhanakan pengunggahan file. Dapatkan URL sementara hanya dengan menentukan model dan file yang akan diunggah.

Prasyarat

Sebelum melakukan panggilan, Anda harus mendapatkan kunci API dan host API, lalu mengonfigurasi kunci API sebagai Variabel lingkungan.

Contoh kode

Python

Konfigurasi Lingkungan

Disarankan menggunakan Python 3.8 atau versi lebih baru.
Instal paket dependensi yang diperlukan.

pip install -U requests

Parameter Input

api_key: Kunci API Model Studio.
model_name: Model yang akan menggunakan file, seperti qwen-vl-plus.
file_path: Jalur file lokal yang akan diunggah, seperti file gambar atau video.

import os
import requests
from pathlib import Path
from datetime import datetime, timedelta

def get_upload_policy(api_key, model_name):
    """Get the file upload credential."""
    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"Failed to get upload policy: {response.text}")
    
    return response.json()['data']

def upload_file_to_oss(policy_data, file_path):
    """Upload the file to the temporary OSS storage."""
    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):
    """Upload the file and get the URL."""
    # 1. Get the upload credential. The API for getting an upload credential is subject to rate limiting. Requests that exceed the limit fail.
    policy_data = get_upload_policy(api_key, model_name) 
    # 2. Upload the file to OSS.
    oss_url = upload_file_to_oss(policy_data, file_path)
    
    return oss_url

# Example
if __name__ == "__main__":
    # Get the API key from an environment variable or set api_key = "your_api_key" in the code.
    api_key = os.getenv("DASHSCOPE_API_KEY")
    if not api_key:
        raise Exception("Set the DASHSCOPE_API_KEY environment variable.")
        
    # Set the model name.
    model_name="qwen-vl-plus"

    # The path of the file to upload.
    file_path = "/tmp/cat.png"  # Replace with the actual file path.
    
    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. It is valid for 48 hours. 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/zh/model-studio/get-temporary-file-url#http-call")

    except Exception as e:
        print(f"Error: {str(e)}")

Output contoh

File uploaded successfully. It is valid for 48 hours. Expiration time: 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/zh/model-studio/get-temporary-file-url#http-call

Penting

Setelah mendapatkan URL sementara, Anda harus menambahkan parameter X-DashScope-OssResourceResolve: enable ke header permintaan HTTP saat melakukan panggilan. Untuk informasi selengkapnya, lihat Panggilan menggunakan HTTP.

Java

Konfigurasi Lingkungan

Disarankan menggunakan JDK 1.8 atau versi lebih baru.
Impor dependensi berikut ke dalam file pom.xml proyek Maven Anda.

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

Parameter Input

apiKey: Kunci API untuk mengakses Model Studio.
modelName: Model yang akan menggunakan file, seperti qwen-vl-plus.
filePath: Jalur file lokal yang akan diunggah, seperti file gambar atau video.

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("Failed to get upload policy: " +
                            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("Failed to upload file: " +
                        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) {
        // Get the API key from the environment variable.
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            System.err.println("Set the DASHSCOPE_API_KEY environment variable.");
            System.exit(1);
        }
        // Model name.
        String modelName = "qwen-vl-plus";
        // Replace with the actual file path.
        String filePath = "src/main/resources/tmp/cat.png";

        try {
            // Check if the file exists.
            File file = new File(filePath);
            if (!file.exists()) {
                System.err.println("File does not exist: " + 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("File uploaded successfully. It is valid for 48 hours. Expiration time: " + expireTime.format(formatter));
            System.out.println("Temporary URL: " + publicUrl);
            System.out.println("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/zh/model-studio/get-temporary-file-url#http-call");
        } catch (IOException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Output contoh

File uploaded successfully. It is valid for 48 hours. Expiration time: 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/zh/model-studio/get-temporary-file-url#http-call

Penting

Metode 2: Unggah file menggunakan antarmuka baris perintah

Bagi developer yang terbiasa menggunakan command line, gunakan antarmuka baris perintah (CLI) yang disediakan oleh DashScope untuk mengunggah file. Setelah menjalankan perintah, Anda akan mendapatkan URL sementara.

Prasyarat

Lingkungan: Disarankan menggunakan Python 3.8 atau versi lebih baru.
Kunci API: Sebelum memulai, dapatkan kunci API.
Instal SDK: Versi DashScope Python SDK harus 1.24.0 atau lebih baru. Jalankan perintah berikut untuk menginstal atau memperbaruinya:

pip install -U dashscope

Metode 1: Gunakan variabel lingkungan (disarankan)

Metode ini lebih aman karena mencegah kunci API terekspos dalam teks biasa di riwayat perintah atau skrip Anda.

Prasyarat: Anda harus telah mengonfigurasi kunci API sebagai variabel lingkungan.

Jalankan perintah unggah:

dashscope oss.upload --model qwen-vl-plus --file cat.png

Output Sampel:

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

Penting

Metode 2: Tentukan kunci API menggunakan parameter baris perintah (untuk penggunaan sementara)

Jalankan perintah unggah:

dashscope oss.upload --model qwen-vl-plus --file cat.png --api_key sk-xxxxxxx

Output Sampel:

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

Penting

Deskripsi parameter baris perintah

Parameter	Diperlukan	Deskripsi	Contoh
oss.upload	Ya	Subperintah DashScope yang digunakan untuk melakukan operasi unggah file.	oss.upload
--model	Ya	Tentukan model mana file akan digunakan.	qwen-vl-plus
--file	Ya	Jalur file lokal. Bisa berupa jalur relatif atau absolut.	cat.png, /data/img.jpg
--api_key	Tidak	Kunci API untuk Model Studio. Parameter ini tidak diperlukan jika variabel lingkungan sudah dikonfigurasi.	sk-xxxx

Langkah 2: Gunakan URL sementara untuk memanggil model

Keterbatasan

Format file: URL sementara harus berupa string URL dengan awalan oss://, yang dihasilkan menggunakan metode yang dijelaskan sebelumnya.
Validitas URL: URL file berlaku selama 48 jam setelah file diunggah.
Konsistensi Model: Model yang Anda gunakan untuk pemanggilan harus sama dengan model yang Anda tentukan saat mengunggah file.
Konsistensi akun: Kunci API untuk panggilan model harus milik Akun Alibaba Cloud yang sama dengan kunci API yang digunakan untuk mengunggah file.

Metode 1: Panggil menggunakan HTTP

Jika Anda memanggil API langsung menggunakan curl, Postman, atau klien HTTP lainnya, Anda harus mengikuti aturan berikut:

Penting

Saat menggunakan URL sementara, Anda harus menambahkan parameter berikut ke header permintaan: X-DashScope-OssResourceResolve: enable.
Jika header ini tidak ada, sistem tidak dapat mengurai tautan oss://, dan permintaan akan gagal. Untuk informasi selengkapnya, lihat Kode error.

Contoh permintaan

Contoh ini menunjukkan cara memanggil qwen-vl-plus untuk mengidentifikasi konten gambar.

Catatan

Ganti oss://... dengan URL sementara sebenarnya. Jika tidak, permintaan gagal.

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": "Apa ini?"},
       {"type": "image_url","image_url": {"url": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"}}]
    }]
}'

Contoh respons

{
  "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": "qwen-vl-plus",
  "id": "chatcmpl-cfc4f2aa-22a8-9a94-8243-44c5bd9899bc"
}

Contoh gambar lokal yang diunggah

Metode 2: Panggil menggunakan DashScope SDK

Gunakan SDK Python atau Java untuk Model Studio.

Teruskan URL secara langsung: Saat memanggil model menggunakan SDK, teruskan string URL dengan awalan oss:// langsung sebagai parameter file.
Tidak perlu khawatir tentang header: SDK secara otomatis menambahkan header permintaan yang diperlukan. Tidak diperlukan operasi tambahan.

Catatan: Tidak semua model mendukung panggilan SDK. Untuk detail lebih lanjut, lihat referensi API model yang bersangkutan.

OpenAI SDK tidak didukung.

Python

Persyaratan

Instal DashScope Python SDK 1.24.0 atau lebih baru.

Contoh Kode

Contoh ini menunjukkan cara memanggil qwen-vl-plus untuk mengidentifikasi konten gambar. Contoh kode ini hanya berlaku untuk model qwen-vl dan omni.

Contoh permintaan

Catatan

Ganti oss://... dalam parameter citra dengan URL sementara Anda yang sebenarnya; jika tidak, permintaan akan gagal.

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

# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: 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)

Contoh tanggapan

{
    "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": "Ini adalah foto seekor kucing yang sedang berlari di atas rumput. Bulu kucing tersebut sebagian besar berwarna putih dengan bintik-bintik cokelat muda, dan matanya berwarna biru, membuatnya terlihat sangat lucu. Latar belakangnya adalah padang rumput hijau yang buram dengan beberapa pohon, dan sinar matahari menambah kesan hangat pada seluruh gambar. Postur kucing tersebut menunjukkan bahwa ia sedang bergerak cepat, mungkin mengejar sesuatu atau hanya menikmati suasana luar ruangan. Secara keseluruhan, ini adalah gambar yang penuh semangat dan hidup."
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 1.112,
        "output_tokens": 91,
        "input_tokens_details": {
            "text_tokens": 21,
            "image_tokens": 1.091
        },
        "prompt_tokens_details": {
            "cached_tokens": 0
        },
        "total_tokens": 1.203,
        "output_tokens_details": {
            "text_tokens": 91
        },
        "image_tokens": 1.091
    }
}

Java

Persyaratan

Instal DashScope Java SDK 2.21.0 atau lebih baru.

Contoh Kode

Contoh ini menunjukkan cara memanggil qwen-vl-plus untuk mengidentifikasi konten gambar. Contoh kode ini hanya berlaku untuk model qwen-vl dan omni.

Contoh permintaan

Catatan

Ganti oss://... dengan URL sementara Anda yang sebenarnya, jika tidak, permintaan akan gagal.

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

    // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: 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("Apa ini?");
        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);
    }

}

Contoh tanggapan

{
    "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": "Ini adalah foto seekor kucing yang berlari di atas rumput. Bulu kucing itu sebagian besar berwarna putih dengan bintik-bintik cokelat muda, dan matanya berwarna biru, membuatnya terlihat sangat lucu. Latar belakangnya adalah padang rumput hijau yang buram dengan beberapa pohon, dan sinar matahari menambahkan nuansa hangat pada keseluruhan gambar. Postur kucing menunjukkan bahwa ia bergerak cepat, mungkin sedang mengejar sesuatu atau hanya menikmati suasana di luar ruangan. Secara keseluruhan, ini adalah gambar yang semarak dan hidup."
                        },
                        {
                            "image_hw": [
                                [
                                    "924",
                                    "924"
                                ]
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Lampiran: Referensi API

Kedua metode untuk mendapatkan URL sementara mengintegrasikan tiga langkah berikut untuk menyederhanakan pengunggahan file. Referensi API untuk setiap langkah disediakan di bawah ini.

Langkah 1: Dapatkan kredensial unggah file

Prasyarat

Dapatkan kunci API dan konfigurasikan kunci API sebagai variabel lingkungan.

Titik akhir API

GET https://dashscope.aliyuncs.com/api/v1/uploads

Penting

API untuk mendapatkan kredensial unggah file dibatasi laju hingga 100 QPS per Akun Alibaba Cloud dan model. Penyimpanan sementara tidak dapat diperluas. Untuk lingkungan produksi atau skenario konkurensi tinggi, gunakan layanan penyimpanan seperti Alibaba Cloud OSS.

Parameter permintaan

Lokasi	Bidang	Tipe	Wajib	Deskripsi	Nilai contoh
Header	Content-Type	string	Ya	Jenis permintaan: application/json.	application/json
Header	Authorization	string	Ya	Kunci API Model Studio, misalnya: Bearer sk-xxx.	Bearer sk-xxx
Params	action	string	Ya	Jenis operasi. Dalam skenario ini, nilainya adalah `getPolicy`.	getPolicy
Params	model	string	Ya	Nama model yang akan dipanggil.	qwen-vl-plus

Parameter respons

Bidang	Tipe	Deskripsi	Nilai contoh
request_id	string	ID unik dari permintaan.	7574ee8f-...-11c33ab46e51
data	objek	-	-
data.policy	string	Kredensial unggah.	eyJl...1ZSJ9XX0=
data.signature	string	Tanda tangan dari kredensial unggah.	g5K...d40=
data.upload_dir	string	Folder untuk mengunggah file.	dashscope-instant/xxx/2024-07-18/xxxx
data.upload_host	string	Alamat host untuk unggahan.	https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com
data.expire_in_seconds	string	Masa berlaku kredensial dalam detik. Catatan Setelah kredensial kedaluwarsa, Anda harus memanggil Operasi API ini lagi untuk mendapatkan yang baru.	300
data.max_file_size_mb	string	Ukuran maksimum file yang dapat diunggah, dalam MB. Nilai ini terkait dengan model yang akan diakses.	100
data.capacity_limit_mb	string	Batas kapasitas unggahan harian untuk Akun Alibaba Cloud, dalam MB.	999999999
data.oss_access_key_id	string	Kunci akses yang digunakan untuk unggahan.	LTAxxx
data.x_oss_object_acl	string	Izin akses untuk file yang diunggah. Nilai `private` menunjukkan bahwa file bersifat pribadi.	private
data.x_oss_forbid_overwrite	string	Menentukan apakah akan menimpa file dengan nama yang sama. Nilai `true` menunjukkan bahwa file tidak dapat ditimpa.	true

Permintaan contoh

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'

Catatan

Jika Anda belum mengonfigurasi Kunci API Model Studio sebagai Variabel Lingkungan, ganti $DASHSCOPE_API_KEY dengan Kunci API Anda. Sebagai contoh, --header "Authorization: Bearer sk-xxx".

Respons contoh

{
    "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"
    }
}

Langkah 2: Unggah file ke ruang penyimpanan sementara

Prasyarat

Dapatkan kredensial unggah file.
Pastikan bahwa kredensial unggah file belum kedaluwarsa. Jika kredensial telah kedaluwarsa, panggil API pada Langkah 1 lagi untuk mendapatkan yang baru.
Untuk memeriksa masa berlaku kredensial unggah file, lihat parameter respons data.expire_in_seconds dari Langkah 1. Nilainya dalam detik.

Titik akhir API

POST {data.upload_host}

Catatan

Ganti {data.upload_host} dengan nilai parameter respons data.upload_host dari Langkah 1.

Parameter permintaan

Lokasi	Bidang	Tipe	Wajib	Deskripsi	Nilai contoh
Header	Content-Type	string	Tidak	Formulir harus dikirimkan sebagai `multipart/form-data`. Saat Anda mengirim formulir, Content-Type ditampilkan dalam format `multipart/form-data;boundary=xxxxxx`. Boundary adalah string yang dihasilkan secara acak yang tidak perlu Anda tentukan. Jika Anda menggunakan SDK untuk membuat formulir, SDK juga secara otomatis menghasilkan nilai acak ini.	multipart/form-data; boundary=9431149156168
form-data	OSSAccessKeyId	text	Ya	Nilai dari parameter respons `data.oss_access_key_id` dari API untuk mendapatkan kredensial unggah file.	LTAm5xxx
	policy	text	Ya	Nilai dari parameter respons `data.policy` dari API untuk mendapatkan kredensial unggah file.	g5K...d40=
	Signature	text	Ya	Nilai dari parameter respons `data.signature` dari API untuk mendapatkan kredensial unggah file.	Sm/tv7DcZuTZftFVvt5yOoSETsc=
	key	text	Ya	Nilai dari parameter respons `data.upload_dir` dari API untuk mendapatkan kredensial unggah file, ditambah dengan `/namafile`.	Sebagai contoh, jika `upload_dir` adalah `dashscope-instant/xxx/2024-07-18/xxx` dan nama file yang akan diunggah adalah `cat.png`, jalur penuh yang dihasilkan adalah: `dashscope-instant/xxx/2024-07-18/xxx/cat.png`
	x-oss-object-acl	text	Ya	Nilai dari parameter respons `data.x_oss_object_acl` dari API untuk mendapatkan kredensial unggah file.	private
	x-oss-forbid-overwrite	text	Ya	Nilai dari parameter respons `data.x_oss_forbid_overwrite` dari API untuk mendapatkan kredensial unggah file.	true
	success_action_status	text	Tidak	Nilainya biasanya 200. Setelah unggahan selesai, API mengembalikan kode status HTTP 200 untuk menunjukkan bahwa operasi berhasil.	200
	file	text	Ya	File atau konten teks. Catatan Hanya satu file yang dapat diunggah pada satu waktu. File harus menjadi bidang formulir terakhir. Bidang formulir lainnya tidak memiliki urutan tertentu.	Sebagai contoh, jika file yang akan diunggah, `cat.png`, disimpan di path `/tmp` dalam sistem Linux, nilai di sini haruslah `file=@"/tmp/cat.png"`.

Parameter respons

Jika pemanggilan berhasil, API ini tidak mengembalikan parameter respons.

Permintaan contoh

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

Langkah 3: Hasilkan URL file

URL file dibuat dengan menggabungkan oss:// dan nilai key (parameter permintaan key dari Langkah 2). URL ini berlaku selama 48 jam.

oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png

Kode kesalahan

Jika panggilan API gagal dan mengembalikan pesan error, lihat Pesan error untuk troubleshooting.

API ini juga mengembalikan kode status berikut.

Kode status HTTP	Kode kesalahan	Pesan kesalahan	Deskripsi
400	invalid_parameter_error	InternalError.Algo.InvalidParameter: URL yang diberikan tampaknya tidak valid. Pastikan formatnya benar.	URL tidak valid. Periksa apakah URL tersebut benar. Jika Anda menggunakan URL file sementara, pastikan header permintaan mencakup parameter `X-DashScope-OssResourceResolve: enable`.
400	InvalidParameter.DataInspection	Format media tidak didukung atau salah untuk inspeksi data.	Alasan yang mungkin termasuk yang berikut: Header permintaan kehilangan parameter yang diperlukan. Atur `X-DashScope-OssResourceResolve: enable`. Format citra yang diunggah tidak memenuhi persyaratan model. Untuk informasi lebih lanjut, lihat Pesan kesalahan.
403	AccessDenied	Tidak valid menurut Kebijakan: Kebijakan telah kedaluwarsa.	Kredensial unggah file telah kedaluwarsa. Panggil API kredensial unggah file lagi untuk menghasilkan kredensial baru.
429	Throttling.RateQuota	Batas laju permintaan terlampaui, silakan coba lagi nanti.	Frekuensi panggilan telah memicu pembatasan laju. API kredensial unggah file dibatasi hingga 100 QPS per Akun Alibaba Cloud dan model. Jika pembatasan kecepatan dipicu, kurangi frekuensi permintaan atau migrasikan ke layanan penyimpanan Anda sendiri, seperti OSS, untuk menghindari batasan.

FAQ

T: Apa yang harus saya lakukan jika terjadi error saat menggunakan URL dengan awalan `oss://`?

J: Ikuti langkah-langkah berikut untuk troubleshooting:

Periksa header permintaan:
Jika Anda memanggil API langsung melalui HTTP (menggunakan alat seperti Postman atau curl), tambahkan parameter X-DashScope-OssResourceResolve: enable ke Header. Tanpa parameter ini, server tidak dapat mengenali protokol OSS internal. Untuk informasi selengkapnya tentang konfigurasi header permintaan, lihat Panggilan menggunakan HTTP.
Periksa validitas URL:
Tautan oss:// adalah URL sementara. Pastikan tautan tersebut dihasilkan dalam 48 jam terakhir. Jika tautan telah kedaluwarsa, unggah file lagi untuk mendapatkan URL baru.

T: Apakah kunci API yang digunakan untuk unggah file dan panggilan model bisa berbeda?

J: Penyimpanan file dan izin akses dikelola berdasarkan Akun Alibaba Cloud Anda. Kunci API hanyalah kredensial akses untuk akun tersebut.

Oleh karena itu, Anda dapat menggunakan Kunci API yang berbeda asalkan mereka termasuk dalam Akun Alibaba Cloud yang sama. Namun, Anda tidak dapat menggunakan Kunci API dari Akun Alibaba Cloud yang berbeda karena pemanggilan model tidak dapat membaca file lintas akun akibat adanya pemagaran akun.

Pastikan kunci API yang Anda gunakan untuk unggah file dan panggilan model dimiliki oleh Akun Alibaba Cloud yang sama.

Keterbatasan

Cara menggunakan

Langkah 1: Dapatkan URL sementara

Metode 1: Unggah file menggunakan kode

Contoh kode

Python

Java

Metode 2: Unggah file menggunakan antarmuka baris perintah

Prasyarat

Metode 1: Gunakan variabel lingkungan (disarankan)

Metode 2: Tentukan kunci API menggunakan parameter baris perintah (untuk penggunaan sementara)

Deskripsi parameter baris perintah

Langkah 2: Gunakan URL sementara untuk memanggil model

Keterbatasan

Metode 1: Panggil menggunakan HTTP

Contoh permintaan

Contoh respons

Contoh gambar lokal yang diunggah

Metode 2: Panggil menggunakan DashScope SDK

Python

Contoh permintaan

Contoh tanggapan

Java

Contoh permintaan

Contoh tanggapan

Lampiran: Referensi API

Langkah 1: Dapatkan kredensial unggah file

Prasyarat

Titik akhir API

Parameter permintaan

Parameter respons

Permintaan contoh

Respons contoh

Langkah 2: Unggah file ke ruang penyimpanan sementara

Prasyarat

Titik akhir API

Parameter permintaan

Parameter respons

Permintaan contoh

Langkah 3: Hasilkan URL file

Kode kesalahan

FAQ

T: Apa yang harus saya lakukan jika terjadi error saat menggunakan URL dengan awalan oss://?

T: Apakah kunci API yang digunakan untuk unggah file dan panggilan model bisa berbeda?

T: Apa yang harus saya lakukan jika terjadi error saat menggunakan URL dengan awalan `oss://`?