Token360
Sign Up

Upload Asset

POST/v1/assets

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.

Choose one upload source:

  • Upload a local file: send a file from your machine or server.
  • Import from a URL: provide a public HTTPS sourceUrl; Token360 downloads and stores it.
  • Upload Base64 content: provide contentBase64 when you already have encoded file bytes.

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

Upload a local file

Use this source when the file is available on your machine or server. The legacy /api/v1/assets alias supports this local-file source only.

Request Body

filefilerequired

File to upload.

namestring

Optional display name.

groupIdstring

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

assetGroupIdinteger

Legacy upload group ID.

modelstring

Optional target model name for Real Face or Virtual Portrait validation.

Response

codeinteger

Response status code.

dataobject

Uploaded asset record in unified schema.

data.idinteger

Internal asset ID (external uploads return a legacy 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

External 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

BYTEPLUS asset identifier.

data.providerRefsobject

External references keyed by service 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

Local file uploads use the standard response envelope. Missing file returns a validation error. 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

Request

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"

Response

JSON
1{
2  "code": 0,
3  "data": {
4    "id": 123,
5    "assetId": "ua_123",
6    "token360AssetId": "ua_123",
7    "assetGroupId": "library",
8    "tenantId": 1001,
9    "userId": 5001,
10    "name": "avatar.png",
11    "status": "active",
12    "assetKind": "UPLOAD",
13    "mediaType": "image/png",
14    "mimeType": "image/png",
15    "sourceType": "UNIFIED",
16    "fileType": "png",
17    "sizeBytes": 1048576,
18    "filename": "avatar.png",
19    "url": "https://cdn.token360.ai/assets/ua_123.png",
20    "thumbnailUrl": "https://cdn.token360.ai/assets/ua_123_thumb.png",
21    "createdAt": "2026-05-11T10:00:00Z",
22    "updatedAt": "2026-05-11T10:00:00Z"
23  },
24  "msg": "Asset uploaded successfully"
25}
Was this page helpful?