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 .
Como funciona
- Envie um arquivo e especifique o modelo de destino. A API retorna uma URL
oss://. - 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
- Python 3.9 ou superior
- Instale as dependências:
Parâmetro | Descrição | Exemplo |
|---|---|---|
| Chave de API do Model Studio | Lida da variável de ambiente |
| Modelo que consumirá o arquivo |
|
| Caminho para o arquivo local |
|
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.
HTTP
Ao chamar a API via HTTP (curl, Postman, etc.), adicione este cabeçalho:
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.
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
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.
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
Parâmetros da solicitação
Localização | Campo | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|---|
Header | Content-Type | _string_ | Sim | Tipo de solicitação. |
|
Header | Authorization | _string_ | Sim | Chave de API do Model Studio. |
|
Params | action | _string_ | Sim | Tipo de operação. Defina como |
|
Params | model | _string_ | Sim | Nome do modelo de destino. |
|
Parâmetros da resposta
Campo | Tipo | Descrição | Exemplo |
|---|---|---|---|
request_id | _string_ | ID exclusivo da solicitação. |
|
data | _object_ | - | - |
data.policy | _string_ | Credencial de envio. |
|
data.signature | _string_ | Assinatura da credencial. |
|
data.upload_dir | _string_ | Caminho do diretório de envio. |
|
data.upload_host | _string_ | Host do OSS para envio. | |
data.expire_in_seconds | _string_ | Validade da credencial em segundos. Obtenha uma nova credencial após a expiração. |
|
data.max_file_size_mb | _string_ | Tamanho máximo do arquivo de envio em MB. Varia conforme o modelo. |
|
data.capacity_limit_mb | _string_ | Capacidade diária de envio por conta Alibaba Cloud em MB. |
|
data.oss_access_key_id | _string_ | Chave de acesso para o envio. |
|
data.x_oss_object_acl | _string_ | Permissão de acesso do arquivo enviado. |
|
data.x_oss_forbid_overwrite | _string_ | Indica se a substituição de arquivos com o mesmo nome está bloqueada. |
|
Solicitação de exemplo
Se a chave de API não estiver configurada como variável de ambiente, substitua$DASHSCOPE_API_KEYpela sua chave de API:--header "Authorization: Bearer sk-xxx".
Resposta de exemplo
Enviar o arquivo para o armazenamento temporário
Substitua{data.upload_host}pelo valor dedata.upload_hostobtido 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 |
|
form-data | OSSAccessKeyId | _text_ | Sim | Valor de |
|
form-data | policy | _text_ | Sim | Valor de |
|
form-data | Signature | _text_ | Sim | Valor de |
|
form-data | key | _text_ | Sim | Valor de |
|
form-data | x-oss-object-acl | _text_ | Sim | Valor de |
|
form-data | x-oss-forbid-overwrite | _text_ | Sim | Valor de |
|
form-data | success_action_status | _text_ | Não | Código de status HTTP retornado em caso de sucesso. Geralmente |
|
form-data | file | _file_ | Sim | Arquivo a ser enviado. Apenas um arquivo por solicitação. O campo |
|
Solicitação de exemplo
Construir a URL do arquivo
Concatene oss:// com a key da solicitação de envio. Esta URL é válida por 48 horas.
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 |
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 |
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:
- Verifique o cabeçalho da solicitação. Ao chamar a API via HTTP (curl, Postman, etc.), adicione
X-DashScope-OssResourceResolve: enableao cabeçalho da solicitação. Sem esse cabeçalho, o servidor não consegue resolver o protocolooss://. O SDK do DashScope adiciona esse cabeçalho automaticamente. - 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.