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
required
要上传的本地文件,单个文件最大 100MB
string
资源类型。常用值:imagevideoaudiofile。不传时服务端会根据文件类型推断
string
资源用途。当前对外接口仅支持 temp_input,不传时默认 temp_input
integer
临时资源有效小时数。不传时默认 48 小时

响应参数

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

代码示例

响应示例

在模型请求中使用

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

Authorizations

Authorization
string
header
required

API Key,格式:Bearer your_api_key

Body

multipart/form-data
file
file
required

要上传的本地文件,单个文件最大 100MB

media_type
enum<string>

资源类型。不传时服务端根据文件类型推断

Available options:
image,
video,
audio,
file
purpose
enum<string>
default:temp_input

资源用途,当前仅支持 temp_input

Available options:
temp_input
ttl_hours
integer
default:48

临时资源有效小时数

Required range: x >= 1

Response

上传结果

id
string

资源 ID;大模型网关响应包含此字段

asset_id
string

资源 ID

asset_uri
string

提交工作流或模型请求时使用的资源引用地址

Example:

"asset://asset_38d2ff7769fb3b7267039941547e6a78"

url
string<uri>

资源访问地址

content_url
string<uri>

资源内容访问地址

signed_url
string<uri>

带签名的临时访问地址

media_type
string

资源类型

mime_type
string

MIME 类型

size_bytes
integer<int64>

文件大小,单位字节

purpose
string

资源用途

persistent
boolean

是否为长期资源

expires_at
string<date-time>

临时资源过期时间

status
string

资源状态

original_filename
string

原始文件名