在调用多模态、图像、视频或音频模型时,通常需要传入文件的 URL。为此,阿里云百炼提供了 免费 临时存储空间,您可将本地文件上传至该空间并获得 URL( 有效期为 48 小时 )。
使用限制
- 文件与模型绑定:文件上传时必须指定模型名称,且该模型须与后续调用的模型一致,不同模型无法共享文件。
- 文件大小限制:接口上传文件大小不得超过1GB,超出限制将导致上传失败。此外,不同模型对输入文件大小有不同限制,超出限制将导致模型调用失败。
- 文件与主账号绑定:文件上传与模型调用所使用的 API Key 必须属于同一个阿里云主账号,且上传的文件仅限该主账号及其对应模型使用,无法被其他主账号或其他模型共享。
- 文件有效期限制:文件上传后有效期48小时,超时后文件将被自动清理,请确保在有效期内完成模型调用。
- 文件使用限制:文件一旦上传,不可查询、修改或下载,仅能通过URL参数在模型调用时使用。
- 文件上传限流:文件上传凭证接口的调用限流按照“阿里云主账号+模型”维度为100QPS,超出限流将导致请求失败。
使用方式
步骤一:获取临时URL
- 方式一:通过代码上传文件
- 方式二:通过命令行工具上传文件
示例代码
- Python
- Java
- 推荐使用Python 3.8及以上版本。
- 请安装必要的依赖包。
- api_key:阿里云百炼API KEY。
- model_name:指定文件将要用于哪个模型,如
qwen-vl-plus。 - file_path:待上传的本地文件路径(图片、视频等)。
步骤二:使用临时URL调用模型
使用限制
- 文件格式:临时URL须通过上述方式生成,且以
oss://为前缀的URL字符串。 - 文件未过期:文件URL仍在上传后的48小时有效期内。
- 模型一致:模型调用所使用的模型必须与文件上传时指定的模型完全一致。
- 账号一致:模型调用的API KEY必须与文件上传时使用的API KEY同属一个阿里云主账号。
方式一:通过HTTP调用
通过curl、Postman或任何其他HTTP客户端直接调用API,则必须遵循以下规则:
- 请求示例
- 响应示例
- 上传的本地图片示例
oss://...替换为真实的临时 URL,否则请求将失败。方式二:通过DashScope SDK调用
您也可以使用阿里云百炼提供的 Python 或 Java SDK。
- 直接传入 URL:调用模型 SDK 时,直接将以
oss://为前缀的URL字符串作为文件参数传入。 - 无需关心 Header:SDK 会自动添加必需的请求头,无需额外操作。
不支持 OpenAI SDK。
- Python
- Java
1.24.0。示例代码本示例为调用 qwen-vl-plus 模型识别图片内容。此代码示例仅适用于 qwen-vl 和 omni 系列模型。- 请求示例
- 响应示例
oss://...替换为真实的临时 URL,否则请求将失败。附接口说明
在上述获取临时URL的两种方式中,代码调用和命令行工具已集成以下三个步骤,简化文件上传操作。以下是各步骤的接口说明。
步骤1:获取文件上传凭证
前提条件
您需要已获取与配置 API Key并配置API Key到环境变量。请求接口
入参描述
传参方式 | 字段 | 类型 | 必选 | 描述 | 示例值 |
|---|---|---|---|---|---|
Header | Content-Type | string | 是 | 请求类型:application/json 。 | application/json |
Authorization | string | 是 | 阿里云百炼API Key,例如:Bearer sk-xxx。 | Bearer sk-xxx | |
Params | action | string | 是 | 操作类型,当前场景为 | getPolicy |
model | string | 是 | 需要调用的模型名称。 | qwen-vl-plus |
出参描述
字段 | 类型 | 描述 | 示例值 |
|---|---|---|---|
request_id | string | 本次请求的系统唯一码。 | 7574ee8f-...-11c33ab46e51 |
data | object | - | - |
data.policy | string | 上传凭证。 | eyJl...1ZSJ9XX0= |
data.signature | string | 上传凭证的签名。 | g5K...d40= |
data.upload_dir | string | 上传文件的目录。 | dashscope-instant/xxx/2024-07-18/xxxx |
data.upload_host | string | 上传的host地址。 | |
data.expire_in_seconds | string | 凭证有效期(单位:秒)。 过期后,重新调用本接口获取新的凭证。 | 300 |
data.max_file_size_mb | string | 本次允许上传的最大文件的大小(单位:MB)。 该值与需要访问的模型相关。 | 100 |
data.capacity_limit_mb | string | 同一个主账号每天上传容量限制(单位:MB)。 | 999999999 |
data.oss_access_key_id | string | 用于上传的access key。 | LTAxxx |
data.x_oss_object_acl | string | 上传文件的访问权限, | private |
data.x_oss_forbid_overwrite | string | 文件同名时是否可以覆盖, | true |
请求示例
$DASHSCOPE_API_KEY替换为实际API Key,例如:--header "Authorization: Bearer sk-xxx"。响应示例
步骤2:上传文件至临时存储空间
前提条件
- 已获取文件上传凭证。
-
确保文件上传凭证在有效期内,若凭证过期,请重新调用步骤1的接口获取新的凭证。
查看文件上传凭证有效期:步骤1的输出参数
data.expire_in_seconds为凭证有效期,单位为秒。
请求接口
data.upload_host对应的值。入参描述
| 传参方式 | 字段 | 类型 | 必选 | 描述 | 示例值 |
|---|---|---|---|---|---|
| Header | Content-Type | string | 否 | 提交表单必须为multipart/form-data。在提交表单时,Content-Type会以multipart/form-data;boundary=xxxxxx的形式展示。boundary 是自动生成的随机字符串,无需手动指定。若使用 SDK 拼接表单,SDK 也会自动生成该随机值。 | multipart/form-data; boundary=9431149156168 |
| form-data | OSSAccessKeyId | text | 是 | 文件上传凭证接口的输出参数 data.oss_access_key_id 的值。 | LTAm5xxx |
| policy | text | 是 | 文件上传凭证接口的输出参数 data.policy 的值。 | g5K...d40= | |
| Signature | text | 是 | 文件上传凭证接口的输出参数 data.signature 的值。 | YOUR_SIGNATURE | |
| key | text | 是 | 文件上传凭证接口的输出参数 data.upload_dir 的值拼接上/ 文件名。 | 例如,upload_dir 为 dashscope-instant/xxx/2024-07-18/xxx,需要上传的文件名为 cat.png,拼接后的完整路径为:dashscope-instant/xxx/2024-07-18/xxx/cat.png | |
| x-oss-object-acl | text | 是 | 文件上传凭证接口的输出参数 data.x_oss_object_acl 的值。 | private | |
| x-oss-forbid-overwrite | text | 是 | 文件上传凭证接口的输出参数中data.x_oss_forbid_overwrite 的值。 | true | |
| success_action_status | text | 否 | 通常取值为 200,上传完成后接口返回 HTTP code 200,表示操作成功。 | 200 | |
| file | text | 是 | 文件或文本内容。
| 例如,待上传文件cat.png在Linux系统中的存储路径为/tmp,则此处应为file=@"/tmp/cat.png"。 |
出参描述
调用成功时,本接口无任何参数输出。
请求示例
步骤3:生成文件URL
文件URL拼接逻辑:oss:// + key (步骤2的入参key)。该URL有效期为 48 小时。
错误码
如果接口调用失败并返回报错信息,请参见错误码进行解决。
本文的API还有特定状态码,具体如下所示。
| HTTP状态码 | 接口错误码(code) | 接口错误信息(message) | 含义说明 |
|---|---|---|---|
| 400 | invalid_parameter_error | InternalError.Algo.InvalidParameter: The provided URL does not appear to be valid. Ensure it is correctly formatted. | 无效URL,请检查URL是否填写正确。
若使用临时文件URL,需确保请求的 Header 中添加了参数 |
| 400 | InvalidParameter.DataInspection | The media format is not supported or incorrect for the data inspection. | 可能的原因有:
|
| 403 | AccessDenied | Invalid according to Policy: Policy expired. | 文件上传凭证已经过期。请重新调用文件上传凭证接口生成新凭证。 |
| 429 | Throttling.RateQuota | Requests rate limit exceeded, please try again later. | 调用频次触发限流。文件上传凭证接口限流为 100 QPS(按阿里云主账号 + 模型维度)。触发限流后,建议降低请求频率,或迁移至 OSS 等自有存储服务以规避限制。 |
常见问题
Q:使用oss://前缀的 URL 调用时报错,该如何处理?
A:请按以下步骤排查:
- 检查请求头(Header):
若您通过 HTTP(如 Postman、curl)直接调用,必须在Header中添加参数X-DashScope-OssResourceResolve: enable。未添加该参数会导致服务端无法识别 OSS 内部协议。关于请求头配置,请参见通过HTTP调用。 - 检查 URL 有效性:
oss://链接为临时 URL,请确保该链接是48小时内生成的。如果链接已过期,请重新上传文件获取新的 URL。
