Token360
Log InSign Up

Upload Asset

POST/v1/assets

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

Use this endpoint for standard asset-library uploads and uploads to Real Face or Virtual Portrait groups. Every upload source returns the same public asset object.

Authentication

Authorization Bearer — JWT session or sk-* API key.

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.

To upload to a group, pass the assetGroupId returned by the asset-group API in the groupId field.

Upload a local file

Use this source when the file is available on your machine or server.

Request Body

filefilerequired

File to upload.

namestring

Optional display name.

groupIdstring

Optional asset group ID returned by GET /v1/asset-groups.

modelstring

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

Response

codeinteger

Response status code.

dataobject

Uploaded asset.

data.assetIdstring

Asset public ID.

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

Media type: IMAGE, VIDEO, AUDIO, or OTHER.

data.assetKindstring

Asset kind, such as USER_UPLOAD, REAL_FACE, or VIRTUAL_PORTRAIT.

data.sourceTypestring

Asset source: UPLOAD, AI_GENERATION, or ASSET_LIFECYCLE.

data.statusstring

Initial status.

data.namestring

Display name.

data.assetTypestring

Asset type label.

data.filenamestring

Stored filename.

data.mimeTypestring

Asset MIME type.

data.sizeBytesstring

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

Stable public error code and message, if available.

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.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": 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}
Was this page helpful?
Upload Asset · Token360