将本地文件上传至免费临时存储空间并获取 oss:// 格式的临时 URL,供多模态、图像、视频或音频模型调用。
在调用多模态、图像、视频或音频模型时,通常需要传入文件的 URL。为此,千问云提供了免费临时存储空间,您可将本地文件上传至该空间并获得 URL(有效期为 48 小时)。
通过 curl、Postman 或任何其他 HTTP 客户端直接调用 API,则必须遵循以下规则:
您也可以使用千问云提供的 Python 或 Java SDK。
在上述获取临时 URL的两种方式中,代码调用和命令行工具已集成以下三个步骤,简化文件上传操作。以下是各步骤的接口说明。
前提条件
您需要已获取 API Key 并配置 API Key 到环境变量。
请求接口
入参描述
出参描述
请求示例
响应示例
前提条件
入参描述
出参描述
调用成功时,本接口无任何参数输出。
请求示例
文件 URL 拼接逻辑**:
如果接口调用失败并返回报错信息,请参见错误信息说明进行解决。
本文的 API 还有特定状态码,具体如下所示。
请按以下步骤排查:
文件存储和访问权限基于千问云账号管理,API Key 仅为账号的访问凭证。
因此,同一千问云账号下的不同 API Key 可正常使用,不同账号的 API Key 因账号隔离,模型调用无法跨账号读取文件。
请确保文件上传与模型调用使用的 API Key 属于同一千问云账号。
使用限制
- 文件与模型绑定:文件上传时必须指定模型名称,且该模型须与后续调用的模型一致,不同模型无法共享文件。此外,不同模型对文件大小有不同限制,超出限制将导致上传失败。
- 文件与主账号绑定:文件上传与模型调用所使用的 API Key 必须属于同一个千问云账号,且上传的文件仅限该主账号及其对应模型使用,无法被其他主账号或其他模型共享。
- 文件有效期限制:文件上传后有效期 48 小时,超时后文件将被自动清理,请确保在有效期内完成模型调用。
- 文件使用限制:文件一旦上传,不可查询、修改或下载,仅能通过 URL 参数在模型调用时使用。
- 文件上传限流:文件上传凭证接口的调用限流按照"千问云账号+模型"维度为 100 QPS,超出限流将导致请求失败。
- 临时 URL 有效期 48 小时,过期后无法使用,请勿用于生产环境。
- 文件上传凭证接口限流为 100 QPS 且不支持扩容,请勿用于生产环境、高并发及压测场景。
- 生产环境建议使用阿里云 OSS 等稳定存储,确保文件长期可用并规避限流问题。
使用方式
- 获取文件 URL:先通过步骤一上传文件(图片、视频或音频),获取以
oss://为前缀的临时 URL。 - 调用模型**:请务必根据步骤二使用临时 URL 进行调用**。该步骤不能跳过,否则接口将报错。
步骤一: 获取临时 URL
- 方式一:通过代码上传文件
- 方式二:通过命令行工具上传文件
本文提供 Python 和 Java 示例代码,简化上传文件操作。您只需指定模型和待上传的文件,即可获取临时 URL。前提条件在调用前,您需要获取 API Key,再配置 API Key 到环境变量。
示例代码
- Python
- Java
环境配置输入参数输出示例
- 推荐使用 Python 3.8 及以上版本。
- 请安装必要的依赖包。
api_key:千问云 API Key。model_name:指定文件将要用于哪个模型,如qwen-vl-plus。file_path:待上传的本地文件路径(图片、视频等)。
获取临时 URL 后,调用时必须在 HTTP 请求头(Header)中显式添加参数**:
X-DashScope-OssResourceResolve: enable**,具体请参见通过 HTTP 调用。步骤二: 使用临时 URL 调用模型
使用限制
- 文件格式:临时 URL 须通过上述方式生成,且以
oss://为前缀的 URL 字符串。 - 文件未过期:文件 URL 仍在上传后的 48 小时有效期内。
- 模型一致:模型调用所使用的模型必须与文件上传时指定的模型完全一致。
- 账号一致:模型调用的 API Key 必须与文件上传时使用的 API Key 同属一个千问云账号。
方式一: 通过 HTTP 调用
通过 curl、Postman 或任何其他 HTTP 客户端直接调用 API,则必须遵循以下规则:
- 使用临时 URL,必须在请求的 Header 中添加参数**:
X-DashScope-OssResourceResolve: enable**。 - 若缺失此 Header,系统将无法解析
oss://链接,请求将失败,报错信息请参考错误码。
- 请求示例
- 响应示例
本示例为调用 qwen-vl-plus 模型识别图片内容。
请将
oss://... 替换为真实的临时 URL,否则请求将失败。方式二:通过 DashScope SDK 调用
您也可以使用千问云提供的 Python 或 Java SDK。
- 直接传入 URL:调用模型 SDK 时,直接将以
oss://为前缀的 URL 字符串作为文件参数传入。 - 无需关心 Header:SDK 会自动添加必需的请求头,无需额外操作。
不支持 OpenAI SDK。
- Python
- Java
前提条件请安装 DashScope Python SDK,且 DashScope Python SDK 版本号 >=
1.24.0。示例代码本示例为调用 qwen-vl-plus 模型识别图片内容。此代码示例仅适用于 qwen-vl 和 omni 系列模型。- 请求示例
- 响应示例
请将 image 参数中的
oss://... 替换为真实的临时 URL,否则请求将失败。附:接口说明
在上述获取临时 URL的两种方式中,代码调用和命令行工具已集成以下三个步骤,简化文件上传操作。以下是各步骤的接口说明。
步骤 1: 获取文件上传凭证
前提条件
您需要已获取 API Key 并配置 API Key 到环境变量。
请求接口
文件上传凭证接口限流为 100 QPS(按"千问云账号+模型"维度),且临时存储不可扩容。生产环境或高并发场景请使用阿里云 OSS 等存储服务。
| 传参方式 | 字段 | 类型 | 必选 | 描述 | 示例值 |
|---|---|---|---|---|---|
| Header | Content-Type | string | 是 | 请求类型:application/json 。 | application/json |
| Header | Authorization | string | 是 | 千问云 API Key,例如:Bearer sk-xxx。 | Bearer sk-xxx |
| Params | action | string | 是 | 操作类型,当前场景为 getPolicy。 | getPolicy |
| Params | 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 地址。 | https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com |
| 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 表示私有。 | private |
| data.x_oss_forbid_overwrite | string | 文件同名时是否可以覆盖,true 表示不可覆盖。 | true |
若未配置千问云 API Key 到环境变量,请将
$DASHSCOPE_API_KEY 替换为实际 API Key,例如:--header "Authorization: Bearer sk-xxx"。步骤 2:上传文件至临时存储空间
前提条件
- 已获取文件上传凭证。
- 确保文件上传凭证在有效期内,若凭证过期,请重新调用步骤 1 的接口获取新的凭证。
查看文件上传凭证有效期:步骤 1 的输出参数
data.expire_in_seconds为凭证有效期,单位为秒。
请将
{data.upload_host} 替换为步骤 1 的输出参数 data.upload_host 对应的值。| 传参方式 | 字段 | 类型 | 必选 | 描述 | 示例值 |
|---|---|---|---|---|---|
| Header | Content-Type | string | 否 | 提交表单必须为 multipart/form-data。在提交表单时,Content-Type 会以 multipart/form-data;boundary=xxxxxx 的形式展示。boundary 是自动生成的随机字符串,无需手动指定。 | multipart/form-data; boundary=9431149156168 |
| form-data | OSSAccessKeyId | text | 是 | 文件上传凭证接口的输出参数 data.oss_access_key_id 的值。 | LTAm5xxx |
| form-data | policy | text | 是 | 文件上传凭证接口的输出参数 data.policy 的值。 | g5K...d40= |
| form-data | Signature | text | 是 | 文件上传凭证接口的输出参数 data.signature 的值。 | Sm/tv7DcZuTZftFVvt5yOoSETsc= |
| form-data | key | text | 是 | 文件上传凭证接口的输出参数 data.upload_dir 的值拼接上 /<文件名>。 | dashscope-instant/xxx/2024-07-18/xxx/cat.png |
| form-data | x-oss-object-acl | text | 是 | 文件上传凭证接口的输出参数 data.x_oss_object_acl 的值。 | private |
| form-data | x-oss-forbid-overwrite | text | 是 | 文件上传凭证接口的输出参数 data.x_oss_forbid_overwrite 的值。 | true |
| form-data | success_action_status | text | 否 | 通常取值为 200,上传完成后接口返回 HTTP code 200,表示操作成功。 | 200 |
| form-data | file | file | 是 | 文件或文本内容。一次只支持上传一个文件。file 必须为最后一个表单域,除 file 以外的其他表单域并无顺序要求。 | 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 中添加了参数 X-DashScope-OssResourceResolve: enable。 |
| 400 | InvalidParameter.DataInspection | The media format is not supported or incorrect for the data inspection. | 可能的原因有:1) 请求 Header 缺少必要参数,请设置 X-DashScope-OssResourceResolve: enable。2) 上传的图片格式不符合模型要求,更多信息请参见错误信息说明。 |
| 403 | AccessDenied | Invalid according to Policy: Policy expired. | 文件上传凭证已经过期。请重新调用文件上传凭证接口生成新凭证。 |
| 429 | Throttling.RateQuota | Requests rate limit exceeded, please try again later. | 调用频次触发限流。文件上传凭证接口限流为 100 QPS(按千问云账号 + 模型维度)。触发限流后,建议降低请求频率,或迁移至 OSS 等自有存储服务以规避限制。 |
常见问题
使用 oss:// 前缀的 URL 调用时报错,该如何处理?
请按以下步骤排查:
- 检查请求头(Header):若您通过 HTTP(如 Postman、curl)直接调用,必须在 Header 中添加参数
X-DashScope-OssResourceResolve: enable。未添加该参数会导致服务端无法识别 OSS 内部协议。关于请求头配置,请参见通过 HTTP 调用。 - 检查 URL 有效性:
oss://链接为临时 URL,请确保该链接是 48 小时内生成的。如果链接已过期,请重新上传文件获取新的 URL。

