上传资产

POST/v1/assets

向当前用户资产库上传文件。

此接口用于普通资产库上传，以及向 Real Face 或 Virtual Portrait 分组上传资产。不同上传方式均返回相同的公开资产对象。

身份验证

Authorization Bearer — JWT 登录会话或 sk-* API Key。

选择一种上传来源：

上传本地文件：从你的机器或服务器发送文件。
从 URL 导入：提供公开 HTTPS sourceUrl，Token360 会下载并存储该文件。
上传 Base64 内容：当你已有 Base64 编码的文件内容时，提供 contentBase64。

如需上传到分组，请将资产分组接口返回的 assetGroupId 填入 groupId 字段。

上传本地文件

当文件位于你的机器或服务器上时，使用此来源。

请求体

filefilerequired

要上传的文件。

namestring

可选展示名称。

groupIdstring

可选资产分组 ID，由 GET /v1/asset-groups 返回。

modelstring

Real Face 或 Virtual Portrait 校验时可选目标模型名称。

响应

codeinteger

响应状态码。

dataobject

上传后的资产。

data.assetIdstring

资产公共 ID。

data.sharedboolean

是否已共享给调用方。

data.sharePermissionstring

共享时的权限。

data.shareExpiresAtstring

共享到期时间（存在时）。

data.assetGroupIdstring

分组公共 ID。

data.groupNamestring

分组名称。

data.mediaTypestring

媒体类型：IMAGE、VIDEO、AUDIO 或 OTHER。

data.assetKindstring

资产类型，例如 USER_UPLOAD、REAL_FACE 或 VIRTUAL_PORTRAIT。

data.sourceTypestring

资产来源：UPLOAD、AI_GENERATION 或 ASSET_LIFECYCLE。

data.statusstring

初始状态。

data.namestring

资产名称。

data.assetTypestring

资产类型标签。

data.filenamestring

存储后的文件名。

data.mimeTypestring

资源 MIME 类型。

data.sizeBytesstring

文件大小（字节）。

data.fileTypestring

文件扩展名或格式。

data.widthinteger

图片/视频宽度（单位像素），可用时返回。

data.heightinteger

图片/视频高度（单位像素），可用时返回。

data.aspectRatiostring

图片/视频宽高比，可用时返回。

data.durationSecondsnumber

音视频时长（秒），可用时返回。

data.frameRatenumber

视频帧率，可用时返回。

data.providerLastErrorobject

最近一次处理错误的稳定代码和通用提示（如有）。

data.urlstring

访问链接。

data.thumbnailUrlstring

缩略图链接（如果有）。

data.expiresAtstring

到期时间（如果有）。

data.requestIdstring

任务链路请求 ID。

data.modelNamestring

生成资源使用的模型名。

data.modelTypestring

生成资源使用的模型类型。

data.originalFilenamestring

上传时原始文件名。

data.createdAtstring

创建时间。

data.updatedAtstring

更新时间。

msgstring

响应信息。

serviceCodestring | null

失败时的业务码。

错误处理

本地文件上传使用标准响应结构。缺失 file 会返回校验错误。文件大小被拒绝时会返回 ASSET_FILE_TOO_LARGE。

常见 serviceCode：

UNIFIED_ASSET_FILE_REQUIRED
UNIFIED_ASSET_GROUP_REQUIRED
UNIFIED_ASSET_GROUP_NOT_FOUND
ASSET_GROUP_NOT_FOUND
ASSET_GROUP_ACCESS_DENIED
ASSET_GROUP_NOT_ACTIVE
ASSET_GROUP_TYPE_UNSUPPORTED
ASSET_GROUP_PROVIDER_REF_MISSING
ASSET_FILE_REQUIRED
ASSET_FILE_TYPE_UNSUPPORTED
ASSET_FILE_TOO_LARGE
ASSET_PROVIDER_REJECTED
ASSET_PROVIDER_UNAVAILABLE

请求

Shell

1curl -X POST https://api.token360.ai/v1/assets \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -F "file=@./avatar.png" \
4  -F "name=avatar.png" \
5  -F "groupId=library"

响应

JSON

1{
2  "code": 200,
3  "data": {
4    "assetId": "ua_123",
5    "assetGroupId": "library",
6    "name": "avatar.png",
7    "status": "active",
8    "assetKind": "USER_UPLOAD",
9    "mediaType": "IMAGE",
10    "mimeType": "image/png",
11    "sourceType": "UPLOAD",
12    "fileType": "png",
13    "sizeBytes": "1048576",
14    "filename": "avatar.png",
15    "url": "https://cdn.token360.ai/assets/ua_123.png",
16    "thumbnailUrl": "https://cdn.token360.ai/assets/ua_123_thumb.png",
17    "createdAt": "2026-05-11T10:00:00Z",
18    "updatedAt": "2026-05-11T10:00:00Z"
19  },
20  "msg": "success"
21}

此页面对您有帮助吗？