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

Saat memanggil model multi-modal seperti model gambar, video, atau audio, Anda seringkali perlu menyediakan URL file. Untuk mempermudah hal ini, Alibaba Cloud Model Studio menyediakan ruang penyimpanan sementara gratis. Anda dapat mengunggah file lokal ke ruang ini dan mendapatkan URL yang valid selama 48 jam.

Penting

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

Keterbatasan

Pengikatan File-Model: Anda harus menentukan nama model saat mengunggah file. Model ini harus merupakan model yang sama yang digunakan dalam pemanggilan berikutnya karena model yang berbeda tidak dapat berbagi file. Selain itu, setiap model memiliki batas ukuran file tertentu. Jika Anda melebihi batas tersebut, unggahan 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.
Masa Berlaku File: Setelah file diunggah, file tersebut valid selama 48 jam, setelah itu file akan dihapus secara otomatis. Pastikan Anda menyelesaikan pemanggilan model dalam periode validitas ini.
Batas Penggunaan File: Setelah file diunggah, file tersebut tidak dapat di-query, dimodifikasi, atau diunduh. File tersebut hanya dapat digunakan sebagai parameter URL dalam pemanggilan model.
Pembatasan Laju Unggah: API untuk mendapatkan kredensial unggah 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 kredensial unggah dibatasi hingga 100 QPS dan tidak mendukung penskalaan keluar. Jangan gunakan dalam lingkungan produksi, skenario konkurensi tinggi, atau skenario uji stres.
Untuk lingkungan produksi, gunakan layanan penyimpanan stabil seperti Alibaba Cloud OSS untuk memastikan ketersediaan file jangka panjang dan menghindari masalah pembatasan laju.

Prosedur

Langkah 1: Unggah file, seperti file gambar, video, atau audio, untuk mendapatkan URL sementara yang diawali dengan oss://.
Langkah 2: Gunakan URL sementara untuk memanggil model.
Saat memanggil model menggunakan HTTP, seperti dengan curl atau Postman, tambahkan X-DashScope-OssResourceResolve: enable ke header permintaan. Jika Anda menggunakan DashScope SDK resmi, Anda dapat melewati langkah ini karena SDK menambahkan header secara otomatis.

Langkah 1: Dapatkan URL sementara

Metode 1: Unggah file menggunakan kode

Topik ini menyediakan contoh kode Python dan Java untuk menyederhanakan proses unggah file. Cukup tentukan model dan file yang akan diunggah untuk mendapatkan URL sementara.

Prasyarat

Sebelum melakukan panggilan, Anda harus memperoleh dan mengonfigurasi Kunci API, lalu atur 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 Anda.
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):
    """Dapatkan kredensial unggah file."""
    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"Gagal mendapatkan kebijakan unggah: {response.text}")
    
    return response.json()['data']

def upload_file_to_oss(policy_data, file_path):
    """Unggah file ke penyimpanan OSS sementara."""
    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"Gagal mengunggah file: {response.text}")
    
    return f"oss://{key}"

def upload_file_and_get_url(api_key, model_name, file_path):
    """Unggah file dan dapatkan URL."""
    # 1. Dapatkan kredensial unggah. API untuk mendapatkan kredensial unggah tunduk pada pembatasan laju. Permintaan yang melebihi batas gagal.
    policy_data = get_upload_policy(api_key, model_name) 
    # 2. Unggah file ke OSS.
    oss_url = upload_file_to_oss(policy_data, file_path)
    
    return oss_url

# Contoh
if __name__ == "__main__":
    # Dapatkan kunci API dari variabel lingkungan atau atur api_key = "your_api_key" dalam kode.
    api_key = os.getenv("DASHSCOPE_API_KEY")
    if not api_key:
        raise Exception("Atur variabel lingkungan DASHSCOPE_API_KEY.")
        
    # Tetapkan nama model.
    model_name="qwen-vl-plus"

    # Jalur file yang akan diunggah.
    file_path = "/tmp/cat.png"  # Ganti dengan jalur file sebenarnya.
    
    try:
        public_url = upload_file_and_get_url(api_key, model_name, file_path)
        expire_time = datetime.now() + timedelta(hours=48)
        print(f"File berhasil diunggah. Valid selama 48 jam. Waktu kedaluwarsa: {expire_time.strftime('%Y-%m-%d %H:%M:%S')}")
        print(f"URL Sementara: {public_url}")
        print("Saat menggunakan URL ini, lihat Langkah 2 dalam dokumentasi untuk menghindari kesalahan.")

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

Contoh Keluaran

File berhasil diunggah. Valid selama 48 jam. Waktu kedaluwarsa: 2024-07-18 17:36:15
URL Sementara: oss://dashscope-instant/xxx/2024-07-18/xxx/cat.png
Saat menggunakan URL ini, lihat Langkah 2 dalam dokumentasi untuk menghindari kesalahan.

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 Model Studio Anda.
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("Gagal mendapatkan kebijakan unggah: " +
                            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("Gagal mengunggah 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) {
        // Dapatkan kunci API dari variabel lingkungan.
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            System.err.println("Atur variabel lingkungan DASHSCOPE_API_KEY.");
            System.exit(1);
        }
        // Nama model.
        String modelName = "qwen-vl-plus";
        // Ganti dengan jalur file sebenarnya.
        String filePath = "src/main/resources/tmp/cat.png";

        try {
            // Periksa apakah file ada.
            File file = new File(filePath);
            if (!file.exists()) {
                System.err.println("File tidak ada: " + 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 berhasil diunggah. Valid selama 48 jam. Waktu kedaluwarsa: " + expireTime.format(formatter));
            System.out.println("URL Sementara: " + publicUrl);
            System.out.println("Saat menggunakan URL ini, lihat Langkah 2 dalam dokumentasi untuk menghindari kesalahan.");
        } catch (IOException e) {
            System.err.println("Kesalahan: " + e.getMessage());
        }
    }
}

Contoh Keluaran

File berhasil diunggah. Valid selama 48 jam. Waktu kedaluwarsa: 2024-07-18 17:36:15
URL Sementara: oss://dashscope-instant/xxx/2024-07-18/xxx/cat.png
Saat menggunakan URL ini, lihat Langkah 2 dalam dokumentasi untuk menghindari kesalahan.

Metode 2: Unggah file menggunakan antarmuka baris perintah

Untuk pengembang yang terbiasa dengan baris perintah, Anda dapat menggunakan antarmuka baris perintah (CLI) yang disediakan oleh DashScope untuk mengunggah file. Setelah menjalankan perintah, Anda mendapatkan URL sementara.

Prasyarat

Lingkungan: Disarankan menggunakan Python 3.8 atau versi lebih baru.
Kunci API: Sebelum memulai, Anda harus memperoleh dan mengonfigurasi 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 atur 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

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

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 Model Studio. Jika Anda telah mengonfigurasi variabel lingkungan, Anda tidak perlu menentukan parameter ini.	sk-xxxx

Langkah 2: Gunakan URL sementara untuk pemanggilan model

Keterbatasan

Format File: URL sementara harus dibuat menggunakan metode yang dijelaskan di atas dan harus berupa string URL dengan awalan oss://.
File Belum Kedaluwarsa: URL file valid selama 48 jam setelah diunggah.
Konsistensi Model: Model yang Anda gunakan untuk pemanggilan harus sama dengan model yang Anda tentukan saat mengunggah file.
Konsistensi Akun: Kunci API untuk pemanggilan model harus milik Akun Alibaba Cloud yang sama dengan Kunci API yang Anda gunakan untuk mengunggah file.

Prasyarat

Sebelum melakukan panggilan, Anda harus mengaktifkan layanan model dan memperoleh Kunci API, lalu atur Kunci API sebagai Variabel Lingkungan.

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 hilang, sistem tidak dapat mengurai tautan oss://, dan permintaan gagal. Untuk informasi lebih lanjut tentang kesalahan, lihat Kode Kesalahan.

Contoh permintaan

Contoh ini menunjukkan cara memanggil model qwen-vl-plus untuk mengidentifikasi isi 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": "Ini adalah gambar seekor kucing putih berlari di atas rumput. Kucing tersebut memiliki mata biru dan tampak sangat lucu dan hidup. Latar belakangnya adalah adegan alam yang kabur, yang menekankan subjek—kucing kecil yang sedang berlari. Teknik fotografi ini disebut depth of field dangkal (atau efek aperture besar). Ini membuat kucing di latar depan tajam dan jelas, sementara latar belakang kabur untuk menonjolkan subjek dan menciptakan efek seperti mimpi. Secara keseluruhan, foto ini memberikan perasaan santai dan menyenangkan serta menangkap perilaku hewan pada saat itu dengan sangat baik.",
        "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

Anda juga dapat menggunakan Python atau Java SDK yang disediakan oleh Model Studio.

Langsung Teruskan URL: Saat Anda memanggil model SDK, langsung teruskan string URL dengan awalan oss:// sebagai parameter file.
Tidak Perlu Khawatir Tentang Header: SDK secara otomatis menambahkan header permintaan yang diperlukan. Tidak ada operasi tambahan yang diperlukan.

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

OpenAI SDK tidak didukung.

Python

Persyaratan

Anda harus menginstal DashScope Python SDK, dan versinya harus 1.24.0 atau lebih baru.

Contoh Kode

Contoh ini menunjukkan cara memanggil model qwen-vl-plus untuk mengidentifikasi isi dari sebuah citra. Contoh kode ini hanya berlaku untuk model qwen-vl dan seri 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

Pastikan Anda menginstal DashScope Java SDK, dan versinya adalah 2.21.0 atau lebih baru.

Contoh Kode

Contoh ini menunjukkan cara memanggil model qwen-vl-plus untuk mengidentifikasi isi dari sebuah citra. Contoh kode ini hanya berlaku untuk model qwen-vl dan seri 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": 1.112,
        "output_tokens": 91,
        "total_tokens": 1.203,
        "image_tokens": 1.091,
        "input_tokens_details": {
            "text_tokens": 21,
            "image_tokens": 1.091
        },
        "output_tokens_details": {
            "text_tokens": 91
        }
    },
    "output": {
        "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."
                        },
                        {
                            "image_hw": [
                                [
                                    "924",
                                    "924"
                                ]
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Lampiran: Referensi API

Dua metode untuk mendapatkan URL sementara, menggunakan kode atau antarmuka baris perintah, mengintegrasikan tiga langkah berikut untuk menyederhanakan pengunggahan file. Referensi API untuk setiap langkah disediakan di bawah ini.

Langkah 1: Dapatkan kredensial unggah file

Prasyarat

Anda telah memperoleh dan mengonfigurasi Kunci API dan menetapkan 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

Metode pengiriman parameter	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 Anda. Contoh: 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

Anda telah memperoleh 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

Metode pengiriman parameter	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 pesan kesalahan dikembalikan, lihat Pesan Kesalahan untuk pemecahan masalah.

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

Apakah kunci API yang digunakan untuk mengunggah file dan pemanggilan model dapat berbeda?

Penyimpanan file dan izin akses dikelola berdasarkan Akun Alibaba Cloud Anda. Kunci API hanya merupakan 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 bahwa Kunci API yang Anda gunakan untuk mengunggah file dan pemanggilan model termasuk dalam Akun Alibaba Cloud yang sama.