Skip to main content
Mais

Upload local files to get temporary URLs

Modelos multimodais como o Qwen-VL exigem URLs de arquivo para entradas de imagem, vídeo e áudio. O Model Studio oferece armazenamento temporário gratuito caso você não tenha URLs públicas: envie um arquivo e obtenha uma URL oss:// válida por 48 horas .

As URLs temporárias destinam-se apenas a desenvolvimento e testes. Não as utilize em produção, cenários de alta concorrência ou testes de estresse. Para cargas de trabalho em produção, use o Object Storage Service (OSS) para garantir disponibilidade de longo prazo e evitar limites de taxa.
Este recurso está disponível apenas na região China (Beijing). Use uma chave de API desta região.

Como funciona

  1. Envie um arquivo e especifique o modelo de destino. A API retorna uma URL oss://.
  2. Informe essa URL na chamada do modelo. É obrigatório concluir a Etapa 2 para usar a URL temporária; ignorá-la causa erros. Para chamadas HTTP, adicione o cabeçalho X-DashScope-OssResourceResolve: enable. O SDK do DashScope adiciona esse cabeçalho automaticamente.

Limitações

Restrição

Detalhe

Vinculação arquivo-modelo

Especifique o nome do modelo no envio. Use o mesmo modelo nas chamadas subsequentes, pois os arquivos não podem ser compartilhados entre modelos diferentes.

Limites de tamanho de arquivo

O tamanho do arquivo não deve exceder 1 GB e precisa respeitar os limites específicos do modelo selecionado.

Vinculação arquivo-conta

As chaves de API usadas para envio e para chamadas de modelo devem pertencer à mesma conta Alibaba Cloud. Não é possível compartilhar arquivos entre contas distintas.

Expiração em 48 horas

Os arquivos são excluídos automaticamente após 48 horas. Conclua as chamadas de modelo dentro desse período.

Sem gerenciamento pós-envio

Não é possível consultar, modificar ou baixar os arquivos. Eles servem apenas como parâmetros de URL nas chamadas de modelo.

Limite de taxa

A API de credenciais de envio tem limite de 100 QPS por conta e por modelo. Solicitações excedentes falham. O armazenamento temporário não suporta scale-out.

Pré-requisitos

Antes de começar:
  • Uma chave de API configurada como variável de ambiente
  • O nome do modelo que consumirá o arquivo (por exemplo, qwen-vl-plus)

Etapa 1: Obter uma URL temporária

Envie um arquivo e obtenha sua URL temporária usando um destes métodos:
  • Upload with code
  • Upload with the CLI
  • Python
  • Java
Pré-requisitos
  • Python 3.9 ou superior
  • Instale as dependências:
pip install -U requests
Parâmetros

Parâmetro

Descrição

Exemplo

api_key

Chave de API do Model Studio

Lida da variável de ambiente DASHSCOPE_API_KEY

model_name

Modelo que consumirá o arquivo

qwen-vl-plus

file_path

Caminho para o arquivo local

/tmp/cat.png

Código de exemplo
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-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):
    """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 (rate-limited to 100 QPS)
    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__":
    # Read the API key from the environment variable
    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"

    # Replace with the actual file path
    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/en/model-studio/get-temporary-file-url#http-call")

    except Exception as e:
        print(f"Error: {str(e)}")
Saída de exemplo
File uploaded successfully. URL 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/en/model-studio/get-temporary-file-url#http-call
Após obter a URL temporária, adicione o cabeçalho X-DashScope-OssResourceResolve: enable às solicitações HTTP ao fazer uma chamada. Para mais informações, consulte Chamada via HTTP.

Etapa 2: Chamar o modelo com a URL temporária

Após enviar um arquivo, use a URL oss:// na chamada do modelo. Duas regras se aplicam:
  • Consistência de modelo: Use o mesmo modelo especificado durante o envio.
  • Consistência de conta: Use uma chave de API pertencente à mesma conta Alibaba Cloud.
Escolha um destes métodos:

HTTP

Ao chamar a API via HTTP (curl, Postman, etc.), adicione este cabeçalho:
X-DashScope-OssResourceResolve: enable
Sem esse cabeçalho, a API não consegue resolver URLs oss:// e as solicitações falham. Solicitação de exemplo Este exemplo chama o qwen-vl-plus para descrever uma imagem enviada.
Substitua oss://... pela sua URL temporária real.
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"}}]
    }]
}'
Resposta de exemplo
{
  "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"
}

SDK do DashScope

O SDK do DashScope gerencia o cabeçalho X-DashScope-OssResourceResolve automaticamente. Basta passar a URL oss:// diretamente como parâmetro de arquivo.
O SDK da OpenAI não é suportado. Nem todos os modelos aceitam chamadas via SDK. Consulte a referência de API do modelo específico para detalhes.
  • Python
  • Java
Pré-requisito: SDK do DashScope para Python 1.24.0 ou superior.Este exemplo chama o qwen-vl-plus para descrever uma imagem enviada. Este código aplica-se aos modelos qwen-vl e omni.
Substitua oss://... no parâmetro de imagem pela sua URL temporária real.
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?"}]
    }]

# If not configured as environment variable, replace with: 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)
Resposta de exemplo
{
    "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": "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,
        "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
    }
}

Referência da API

Os exemplos de código e a CLI na Etapa 1 encapsulam internamente estas três operações de API. Use esta referência para implementar o fluxo de envio manualmente.

Obter uma credencial de envio de arquivo

GET https://dashscope.aliyuncs.com/api/v1/uploads
A API de credenciais tem limite de taxa de 100 QPS por conta e por modelo. O armazenamento temporário não permite scale-out. Para cargas de trabalho em produção ou de alta concorrência, use o Alibaba Cloud OSS.

Parâmetros da solicitação

Localização

Campo

Tipo

Obrigatório

Descrição

Exemplo

Header

Content-Type

_string_

Sim

Tipo de solicitação.

application/json

Header

Authorization

_string_

Sim

Chave de API do Model Studio.

Bearer sk-xxx

Params

action

_string_

Sim

Tipo de operação. Defina como getPolicy.

getPolicy

Params

model

_string_

Sim

Nome do modelo de destino.

qwen-vl-plus

Parâmetros da resposta

Campo

Tipo

Descrição

Exemplo

request_id

_string_

ID exclusivo da solicitação.

7574ee8f-...-11c33ab46e51

data

_object_

-

-

data.policy

_string_

Credencial de envio.

eyJl...1ZSJ9XX0=

data.signature

_string_

Assinatura da credencial.

g5K...d40=

data.upload_dir

_string_

Caminho do diretório de envio.

dashscope-instant/xxx/2024-07-18/xxxx

data.upload_host

_string_

Host do OSS para envio.

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

data.expire_in_seconds

_string_

Validade da credencial em segundos. Obtenha uma nova credencial após a expiração.

300

data.max_file_size_mb

_string_

Tamanho máximo do arquivo de envio em MB. Varia conforme o modelo.

100

data.capacity_limit_mb

_string_

Capacidade diária de envio por conta Alibaba Cloud em MB.

999999999

data.oss_access_key_id

_string_

Chave de acesso para o envio.

LTAxxx

data.x_oss_object_acl

_string_

Permissão de acesso do arquivo enviado. private indica que o arquivo é privado.

private

data.x_oss_forbid_overwrite

_string_

Indica se a substituição de arquivos com o mesmo nome está bloqueada. true significa que a substituição está bloqueada.

true

Solicitação de exemplo

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'
Se a chave de API não estiver configurada como variável de ambiente, substitua $DASHSCOPE_API_KEY pela sua chave de API: --header "Authorization: Bearer sk-xxx" .

Resposta de exemplo

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

Enviar o arquivo para o armazenamento temporário

POST {data.upload_host}
Substitua {data.upload_host} pelo valor de data.upload_host obtido na resposta da credencial.

Parâmetros da solicitação

Localização

Campo

Tipo

Obrigatório

Descrição

Exemplo

Header

Content-Type

_string_

Não

Envie o formulário como multipart/form-data. O boundary é gerado automaticamente pelo seu cliente HTTP.

multipart/form-data; boundary=9431149156168

form-data

OSSAccessKeyId

_text_

Sim

Valor de data.oss_access_key_id da resposta da credencial.

LTAm5xxx

form-data

policy

_text_

Sim

Valor de data.policy da resposta da credencial.

g5K...d40=

form-data

Signature

_text_

Sim

Valor de data.signature da resposta da credencial.

Sm/tv7DcZuTZftFVvt5yOoSETsc=

form-data

key

_text_

Sim

Valor de data.upload_dir da resposta da credencial, concatenado com /<filename>.

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

form-data

x-oss-object-acl

_text_

Sim

Valor de data.x_oss_object_acl da resposta da credencial.

private

form-data

x-oss-forbid-overwrite

_text_

Sim

Valor de data.x_oss_forbid_overwrite da resposta da credencial.

true

form-data

success_action_status

_text_

Não

Código de status HTTP retornado em caso de sucesso. Geralmente 200.

200

form-data

file

_file_

Sim

Arquivo a ser enviado. Apenas um arquivo por solicitação. O campo file deve ser o último campo do formulário.

file=@"/tmp/cat.png"

Em caso de sucesso, a API retorna HTTP 200 sem corpo de resposta.

Solicitação de exemplo

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

Construir a URL do arquivo

Concatene oss:// com a key da solicitação de envio. Esta URL é válida por 48 horas.
oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png

Códigos de erro

Se as chamadas de API falharem, consulte Mensagens de erro para solução de problemas gerais. Estes códigos de erro são específicos para envios de arquivos temporários:

Status HTTP

Código de erro

Mensagem de erro

Causa e resolução

400

invalid_parameter_error

InternalError.Algo.InvalidParameter: The provided URL does not appear to be valid. Ensure it is correctly formatted.

A URL está malformada. Verifique o formato da URL. Se estiver usando uma URL oss:// via HTTP, adicione o cabeçalho X-DashScope-OssResourceResolve: enable.

400

InvalidParameter.DataInspection

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

O cabeçalho da solicitação não contém X-DashScope-OssResourceResolve: enable ou o formato do arquivo não é suportado pelo modelo. Consulte Mensagens de erro.

403

AccessDenied

Invalid according to Policy: Policy expired.

A credencial de envio expirou. Chame a API de credenciais novamente para obter uma nova.

429

Throttling.RateQuota

Requests rate limit exceeded, please try again later.

A taxa de solicitações excede 100 QPS. Reduza a frequência de solicitações ou migre para o OSS para cargas de trabalho em produção.

Perguntas frequentes

O que fazer se uma URL oss:// retornar um erro?

Siga estas etapas:
  1. Verifique o cabeçalho da solicitação. Ao chamar a API via HTTP (curl, Postman, etc.), adicione X-DashScope-OssResourceResolve: enable ao cabeçalho da solicitação. Sem esse cabeçalho, o servidor não consegue resolver o protocolo oss://. O SDK do DashScope adiciona esse cabeçalho automaticamente.
  2. Verifique a validade da URL. A URL oss:// expira 48 horas após o envio. Se tiver expirado, envie o arquivo novamente para obter uma nova URL.

Posso usar chaves de API diferentes para envio de arquivos e chamadas de modelo?

Sim, desde que ambas as chaves de API pertençam à mesma conta Alibaba Cloud. O acesso aos arquivos é gerenciado no nível da conta, não no nível da chave de API. Chaves de API de contas Alibaba Cloud diferentes não conseguem acessar os arquivos enviados umas das outras.
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
API em tempo real
Incorporação de Texto
Produção de Modelos