跳到主要内容

上传素材

POST/xmind-cloud-platform/openapi/volcengine?Action=CreateAsset&Version=2024-01-01

上传素材并同步返回素材 ID,素材入库异步完成。

请求参数​

Action 与 Version 通过查询参数传递,其余参数放在 JSON 请求体中。

URLstring必填

可公网访问的 HTTPS 直链,不支持重定向地址。

默认值:-
Namestring必填

素材名称,最长 128 个字符。

默认值:-
AssetTypestring可选

素材类型:Image、Video、Audio;不传时根据远端 Content-Type 和文件扩展名推断。

默认值:-
GroupIdstring可选

分组 ID,不传表示未分组。上传真人素材时必须携带已验证的真人分组 ID(group-xxx)。

默认值:-
OneTimeboolean可选

是否为一次性素材,默认 false;传 true 时素材被模型调用完成后平台自动删除,创建后不可修改。

默认值:-
接口返回即已创建成功

成功返回后素材已经创建,可以直接用返回的 Id 查询、更新或删除,不需要等待入库完成。

素材入库是异步的,初始 Status 为 Processing。请通过 GetAsset 或 ListAssets 查询状态:成功后为 Active,失败为 Failed。

只接受 HTTPS 公网直链

URL 会由平台下载并保存,只接受 HTTPS 公网地址,会拒绝内网、回环与链路本地地址,也不跟随重定向。

上传真人素材前必须先完成认证

上传真人素材必须携带已验证的真人组 GroupId(group-xxx)。认证未完成时 GroupId 为空,此时上传会返回 400 InvalidRequest(真人素材组不存在或无权访问),需先完成认证拿到 GroupId 再上传。

真人分组只能通过发起真人认证建立:先用发起真人认证拿到 H5 链接,让终端用户完成认证,再用查询真人认证结果取回 GroupId。

认证​

所有接口使用同一套 V4 签名,凭证与签名方式见火山方舟素材库 API 概览。以下请求头为通用要求:

Content-Typestring必填

固定为 application/json。

默认值:application/json
Hoststring必填

实际访问的域名和端口;包含端口时必须写入签名。

默认值:-
X-Datestring必填

UTC 时间,格式 yyyyMMdd'T'HHmmss'Z',例如 20261022T131900Z;与平台时间偏差不能超过 300 秒。

默认值:-
X-Content-Sha256string必填

原始请求体的 SHA-256 小写十六进制。

默认值:-
Authorizationstring必填

V4 HMAC-SHA256 签名。

默认值:-

响应​

Result.Idstring可选

平台素材 ID。

默认值:-
Result.Namestring可选

素材名称。

默认值:-
Result.URLstring可选

预览地址,有效期 1 小时。

默认值:-
Result.AssetTypestring可选

素材类型:Image、Video、Audio。

默认值:-
Result.GroupIdstring可选

所属分组 ID;未分组时为 null,真人素材返回真人分组 ID(group-xxx)。

默认值:-
Result.Statusstring可选

入库状态:Processing、Active、Failed。

默认值:-
Result.OneTimeboolean可选

是否为一次性素材。

默认值:-
Result.CreateTimestring可选

创建时间,UTC 时间字符串。

默认值:-
Result.UpdateTimestring可选

更新时间,UTC 时间字符串。

默认值:-
Result.Moderationobject可选

内容审核信息,通常为 null。

默认值:-
Result.LastInferenceTimestring可选

最近一次推理时间,通常为 null。

默认值:-

错误​

Code说明
400InvalidParameter:参数格式或取值非法
400InvalidRequest:真人素材组不存在或无权访问(认证未完成或跨资源使用真人分组)
401SignatureDoesNotMatch、InvalidTimestamp、XContentSha256Mismatch、MissingParameter.Authorization 等签名或时间相关错误
403AccessDenied 凭证被禁用或无权限;ExpiredToken 凭证已过期
429QuotaWriteQPMExceeded 每分钟写入额度用尽;AccountFlowLimitExceeded 每秒请求上限触发;TooManyRequests 请求过于频繁

相关​