Upload Asset · Token360

Upload a file into the current user's asset library.

Use this endpoint for both standard asset-library uploads and provider-based uploads. The response always uses the unified asset schema.

Authentication

Authorization Bearer

API key as bearer token in Authorization header.

Request Body

filefilerequired

File to upload.

namestring

Optional display name.

groupIdstring

Optional unified group ID from GET /v1/asset-groups.

assetGroupIdinteger

Legacy provider group ID for provider-based uploads.

modelstring

Optional target model name for RealFace or Virtual Portrait validation.

assetGroupId (or groupId with legacy legacy_rf_ prefix) uses the provider-based upload path.

Response

codeinteger

Response status code.

dataobject

Uploaded asset record in unified schema.

data.idinteger

Internal asset ID (provider uploads return legacy provider asset id).

data.assetIdstring

Asset public ID.

data.token360AssetIdstring

Backward-compatible alias of assetId.

data.tenantIdinteger

Tenant ID.

data.userIdinteger

Owner user ID.

data.userNamestring

Owner display name.

data.sharedboolean

Whether the asset is shared with the caller.

data.sharePermissionstring

Share permission when shared.

data.shareExpiresAtstring

Share expiry time when shared.

data.assetGroupIdstring

Asset group public ID.

data.groupNamestring

Asset group name.

data.mediaTypestring

Detected media type.

data.assetKindstring

Asset kind.

data.sourceTypestring

Asset source type.

data.statusstring

Initial status.

data.namestring

Display name.

data.assetTypestring

Asset type label.

data.filenamestring

Stored filename.

data.mimeTypestring

Asset MIME type.

data.sizeBytesinteger

Asset size in bytes.

data.fileTypestring

Asset extension or format.

data.widthinteger

Image/video width in pixels when available.

data.heightinteger

Image/video height in pixels when available.

data.aspectRatiostring

Image/video aspect ratio when available.

data.durationSecondsnumber

Asset duration in seconds when available.

data.frameRatenumber

Video frame rate when available.

data.providerLastErrorobject

Provider-level error details, if any.

data.urlstring

Accessible content URL.

data.thumbnailUrlstring

Thumbnail URL, if available.

data.expiresAtstring

Asset expiry timestamp, if any.

data.requestIdstring

Request ID from generation provenance.

data.modelNamestring

Model name used to produce the asset.

data.modelTypestring

Model type used to produce the asset.

data.byteplusAssetIdstring

Provider identifier for BYTEPLUS assets.

data.providerRefsobject

Provider refs keyed by provider and ref type.

data.originalFilenamestring

Original uploaded filename.

data.createdAtstring

Create timestamp.

data.updatedAtstring

Update timestamp.

msgstring

Response message.

serviceCodestring | null

Service error code on failure.

Error Handling

Asset upload validation uses the standard response envelope. Missing multipart file returns a validation error. Multipart size rejection uses ASSET_FILE_TOO_LARGE.

Common serviceCode values:

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