ContentService
Uploading content: upload sessions straight to storage, validation, the upload quota and cook status.
On this page
- Summary
- Methods
- CreateUploadSession
- GetUploadSession
- GetUploadPartUrls
- CompleteUpload
- AbortUpload
- GetUploadQuota
- GetVersionCooks
- Types
- ContentInfo
- CreateUploadSessionRequest
- GetUploadPartUrlsRequest
- GetUploadPartUrlsResponse
- GetUploadQuotaRequest
- GetVersionCooksRequest
- TargetCook
- UploadPartUrl
- UploadQuota
- UploadSession
- UploadSessionRef
- ValidationProblem
- VersionCooks
- See also
Content uploads, validation and cooking. Uploading a file: 1. CreateUploadSession with the file's SHA-256, size, content type and name. If the platform already has those bytes, the session comes back complete with their URL and nothing is uploaded (a republish uploads only what changed). 2. Otherwise send the bytes the way the session says (method): put one HTTP PUT of the whole file to put_url (presigned, straight to the object store: the bytes never pass through the API) multipart part_count PUTs of part_size bytes (the last one shorter) to the URLs GetUploadPartUrls hands out; resumable: GetUploadSession lists the parts already received proxy one PUT of the whole file to put_url on the API itself, with the same bearer token (deployments without a public object store endpoint; development) 3. CompleteUpload: the platform checks the received bytes against the declared hash and size, validates them (file type by content, limits per asset, no external references) and stores them under their hash. A file that fails comes back rejected with problems saying what is wrong, measured against which limit. Sessions belong to the account that made them and expire (expires_at); every id is public. Every method is a POST with a JSON body; see the overview for the protocol, authentication and errors.
Summary#
| Method | Auth | Description |
|---|---|---|
| CreateUploadSession | Account | |
| GetUploadSession | Account | |
| GetUploadPartUrls | Account | Presigned URLs for some parts of a multipart session (at most 100 per call). |
| CompleteUpload | Account | |
| AbortUpload | Account | |
| GetUploadQuota | Account | The caller's upload quota and what is used of it. |
| GetVersionCooks | unknown | Where cooking a version's content stands, per cook target (the version's creator). |
Methods#
CreateUploadSession#
POST /neo.platform.v1.ContentService/CreateUploadSession
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Also callable with a scoped token: studio.
Request: CreateUploadSessionRequest. Response: UploadSession.
GetUploadSession#
POST /neo.platform.v1.ContentService/GetUploadSession
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Also callable with a scoped token: studio.
Request: UploadSessionRef. Response: UploadSession.
GetUploadPartUrls#
Presigned URLs for some parts of a multipart session (at most 100 per call).
POST /neo.platform.v1.ContentService/GetUploadPartUrls
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Also callable with a scoped token: studio.
Request: GetUploadPartUrlsRequest. Response: GetUploadPartUrlsResponse.
CompleteUpload#
POST /neo.platform.v1.ContentService/CompleteUpload
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Also callable with a scoped token: studio.
Request: UploadSessionRef. Response: UploadSession.
AbortUpload#
POST /neo.platform.v1.ContentService/AbortUpload
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Also callable with a scoped token: studio.
Request: UploadSessionRef. Response: UploadSession.
GetUploadQuota#
The caller's upload quota and what is used of it.
POST /neo.platform.v1.ContentService/GetUploadQuota
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Also callable with a scoped token: studio.
Request: GetUploadQuotaRequest. Response: UploadQuota.
GetVersionCooks#
Where cooking a version's content stands, per cook target (the version's creator).
POST /neo.platform.v1.ContentService/GetVersionCooks
Content-Type: application/jsonAuth: unknown
Also callable with a scoped token: studio.
Request: GetVersionCooksRequest. Response: VersionCooks.
Types#
ContentInfo#
What validation learned about a file.
| Field | Type | Description |
|---|---|---|
kind | string | model, image, audio, json, text, data |
format | string | glb, gltf, png, jpeg, webp, ktx2, exr, wav, ogg, flac, json, text, data |
triangles | string (int64) | |
bones | number | |
width | number | An image's size; for a model, its largest texture. |
height | number | |
durationMs | string (int64) | |
textures | number |
CreateUploadSessionRequest#
| Field | Type | Description |
|---|---|---|
sha256 | string | Lower-case hex SHA-256 of the whole file. |
size | string (int64) | |
contentType | string | e.g. model/gltf-binary, image/png, audio/ogg, application/json, text/plain, application/octet-stream (the platform checks it against what the bytes are). |
name | string | The file's name or project path (models/tree.glb): its extension must fit its content, and validation messages name it. |
GetUploadPartUrlsRequest#
| Field | Type | Description |
|---|---|---|
sessionId | string | |
partNumbers | array of number | 1-based part numbers; empty: every part not received yet (up to 100). |
GetUploadPartUrlsResponse#
| Field | Type | Description |
|---|---|---|
parts | array of UploadPartUrl | |
expiresAt | string |
GetUploadQuotaRequest#
No fields: send {}.
GetVersionCooksRequest#
| Field | Type | Description |
|---|---|---|
experienceId | string | |
versionId | string | ver_...; empty: the live version. |
TargetCook#
| Field | Type | Description |
|---|---|---|
target | string | desktop, web |
status | string | waiting (nothing cooked yet), cooking, done, failed, none (the version has no cookable files) |
total | number | |
done | number | |
failed | number | |
manifestUrl | string | done: the version's cooked manifest for this target (path -> cooked content URL). |
cooker | string | The cooker that made it (platform-passthrough-1, or the engine's neo-cook-x.y.z). |
errors | array of string | failed: the first few failures (models/tree.glb:...). |
UploadPartUrl#
| Field | Type | Description |
|---|---|---|
partNumber | number | |
url | string | |
size | string (int64) |
UploadQuota#
| Field | Type | Description |
|---|---|---|
usedToday | string (int64) | Bytes uploaded in the last 24 hours (open sessions count: their bytes are reserved). |
dailyLimit | string (int64) | |
storageUsed | string (int64) | Bytes of stored content this account uploaded first (content shared with others counts once, for whoever uploaded it first). |
storageLimit | string (int64) | |
maxFileSize | string (int64) | The largest single file. |
openSessions | number | |
openSessionsLimit | number |
UploadSession#
| Field | Type | Description |
|---|---|---|
id | string | upl_... |
status | string | open (waiting for the bytes), complete, rejected (see problems), expired, aborted |
sha256 | string | |
size | string (int64) | |
contentType | string | |
name | string | |
method | string | none (complete already: the platform had the bytes), put, multipart, proxy |
putUrl | string | put and proxy: where to PUT the file. |
putHeaders | object (map of string to string) | Headers to send with every PUT (besides the bearer token for proxy). |
partSize | string (int64) | multipart: every part is part_size bytes but the last. |
partCount | number | |
partsReceived | array of number | multipart: the part numbers already received (to resume). |
expiresAt | string | |
url | string | complete: the content's URL (content-addressed, immutable). |
problems | array of ValidationProblem | rejected: why. |
info | ContentInfo | |
createdAt | string |
UploadSessionRef#
| Field | Type | Description |
|---|---|---|
sessionId | string |
ValidationProblem#
One thing wrong with an uploaded file.
| Field | Type | Description |
|---|---|---|
rule | string | A stable rule id: glb.truncated, glb.external_uri, glb.triangles, image.too_large, type.mismatch, hash.mismatch, size.mismatch,... |
message | string | A sentence for people: what is wrong and how to fix it. |
at | string | Where in the file (images[2], meshes[0].primitives[1]), when it applies. |
measured | string | What was measured and the limit it broke, when the rule is a limit. |
limit | string |
VersionCooks#
| Field | Type | Description |
|---|---|---|
versionId | string | |
targets | array of TargetCook |