Skip to main content
POST
上传资源

上传资源

上传图片、视频、音频或文件,生成可在大模型网关请求中使用的临时资源地址。适用于视频首帧、尾帧、参考图等输入素材。
上传成功后使用返回的 asset_uri 字段值,例如 asset://asset_xxx。提交模型请求时直接把这个字符串放入图片、视频或音频字段,不需要再包一层对象。临时资源默认 48 小时有效。

图片资源支持形式

大模型网关对外统一推荐两种写法:普通字段直接传资源字符串;需要声明素材角色或在提示词里引用素材时,使用 { "uri": "...", "role": "...", "label": "..." } 对象。

公网 URL

图片地址必须能被服务端访问。

Base64 Data URL

使用 data:image/<format>;base64,<data>,其中 <format> 使用小写格式名,例如 pngjpegwebp

资源 ID

先调用本接口上传本地文件,再把返回的 asset_uri 字段值放入图片字段。

带角色或引用标签的对象

只有需要声明首帧、尾帧、参考图等素材角色,或需要在提示词里用 @标签 指向素材时,才使用对象写法。对象里统一使用 uri 存资源字符串。
label 是素材显示名,不需要带 @。在 prompt 里用 @首帧 引用时,服务端会把它绑定到当前请求中的这张图片。

支持图片资源的字段

以下字段会被网关识别并转为上游模型可访问的地址: 图片编辑接口同时支持 OpenAI SDK 常见的 multipart/form-data 文件上传,文件字段包括 imageimage[]mask

请求参数

请求类型为 multipart/form-data
file
file
required
要上传的本地文件,单个文件最大 100MB
media_type
string
资源类型。常用值:imagevideoaudiofile。不传时服务端会根据文件类型推断
purpose
string
资源用途。当前对外接口仅支持 temp_input,不传时默认 temp_input
ttl_hours
integer
临时资源有效小时数。不传时默认 48 小时

响应参数

id
string
资源 ID
asset_id
string
资源 ID,与 id 含义一致
asset_uri
string
资源引用地址,提交模型请求时优先使用,例如 asset://asset_xxx
url
string
资源访问地址
content_url
string
资源内容访问地址,与 url 含义一致
signed_url
string
带签名的临时访问地址
media_type
string
资源类型,例如 image
mime_type
string
MIME 类型,例如 image/png
size_bytes
integer
文件大小,单位字节
purpose
string
资源用途,当前为 temp_input
persistent
boolean
是否为长期资源。临时输入资源一般为 false
expires_at
string
临时资源过期时间
status
string
资源状态。可用状态通常为 confirmed

代码示例

响应示例

在模型请求中使用

媒体字段支持三种写法:
需要声明素材角色,或需要在提示词里用 @标签 引用素材时,可以使用对象写法:
多素材引用示例:
同一个请求里的 label 不能重复;label 可写成 阿九,不要写成普通文本占位。提示词中引用时写 @阿九,也兼容 {{阿九}}