Uploads

The uploads resource is enhanced in two ways:

• create(), retrieve(), and triggerAction() return a response where response.upload gains .wait() — a helper that polls until the upload reaches a terminal state.
• uploadFile() — a one-call wrapper around the full 4-step S3 multipart upload flow (init → upload parts → complete → poll until imported).

---

upload.wait(options?)

Available on response.upload after calling client.uploads.create(), client.uploads.retrieve(), or client.uploads.triggerAction(). Polls until the upload has been processed into an entity (asset or model), or reaches a terminal state (imported, complete, or failed). Resolves with the latest upload data so you can read entityId, status, or errorMessage without a follow-up retrieve.

Signature

upload.wait(options?: UploadWaitOptions): Promise<Upload>

Parameters

Name	Type	Default	Description
options.intervalMs?	number	2000	Polling interval in milliseconds.
options.timeoutMs?	number	300000	Maximum wait time in milliseconds. Throws if exceeded.

Returns

Promise<Upload> — a new Upload instance with the final state. All original upload fields are present.

Errors

Throws Error if the upload does not reach a terminal status within timeoutMs.

Example

import Scenario from '@scenario-labs/sdk';

const client = new Scenario({ apiKey: '...' });

const res = await client.uploads.retrieve('upload_...');
const done = await res.upload.wait();
if (done.status === 'failed') throw new Error(done.errorMessage);
console.log(done.entityId);

Note

.wait() resolves as soon as entityId is populated or a terminal status is reached — whichever comes first. Terminal statuses are 'imported', 'complete', and 'failed'.

---

create(), retrieve(), triggerAction() — enhanced responses

All three base methods are enhanced: each response’s upload field gains .wait().

// After create
const createRes = await client.uploads.create({ fileName: 'photo.jpg', fileSize: 1234, contentType: 'image/jpeg', kind: 'image', parts: 1 });
const done = await createRes.upload.wait();

// After retrieve
const retrieveRes = await client.uploads.retrieve('upload_...');
const done2 = await retrieveRes.upload.wait();

// After triggerAction
const actionRes = await client.uploads.triggerAction('upload_...', { action: 'complete' });
const done3 = await actionRes.upload.wait();

---

client.uploads.uploadFile(params)

Upload a file end-to-end. Computes an optimal part size within AWS S3 limits, uploads all parts in parallel up to partConcurrency at a time, triggers completion, polls until the server validates and imports the file, and returns the resolved entity.

The return type narrows on kind: passing 'model' returns a ModelRetrieveResponse; everything else returns an AssetRetrieveResponse.

Signature

client.uploads.uploadFile<K extends UploadKind>(
  params: UploadFileParams<K>,
  options?: RequestOptions,
): Promise<UploadResult<K>>

Parameters

Name	Type	Default	Description
params.file	UploadFileInput		The file to upload. See UploadFileInput for accepted forms.
params.fileName	string		Original filename (e.g. "photo.jpg").
params.contentType	string		MIME type (e.g. "image/jpeg", "application/octet-stream").
params.kind	UploadKind		Upload kind. Determines the return type: 'model' → ModelRetrieveResponse; everything else → AssetRetrieveResponse. See the API Reference for valid kind values.
params.assetOptions?	object		Extra asset options passed through to the server. Ignored when kind === 'model'.
params.partConcurrency?	number	4	Maximum number of S3 parts uploaded in parallel.
params.pollIntervalMs?	number	2000	Polling interval for the “upload imported” check, in ms.
params.pollTimeoutMs?	number	300000	Maximum time to wait for the upload to finish importing, in ms. Throws if exceeded.

Returns

Promise<UploadResult<K>> — the resolved entity after the upload is fully imported and validated by the server.

kind	Return type
'model'	ModelRetrieveResponse
anything else	AssetRetrieveResponse

Errors

Throws Error in the following cases:

• File is empty (byteLength === 0).
• File exceeds 5 TiB (AWS S3 hard limit).
• Upload reaches 'failed' status — the error message includes the server’s errorMessage.
• Upload does not reach a terminal status within pollTimeoutMs.

try {
  const asset = await client.uploads.uploadFile({
    file: './large-texture.png',
    fileName: 'large-texture.png',
    contentType: 'image/png',
    kind: 'image',
    pollTimeoutMs: 600_000, // extend to 10 min for large files
  });
} catch (err) {
  console.error((err as Error).message);
}

Example

import Scenario from '@scenario-labs/sdk';

const client = new Scenario({ apiKey: '...' });

// From a local file path (Node.js)
const asset = await client.uploads.uploadFile({
  file: './photo.jpg',
  fileName: 'photo.jpg',
  contentType: 'image/jpeg',
  kind: 'image',
});
console.log(asset.id, asset.url);

// From a Blob
const pngBlob = new Blob([pngBytes], { type: 'image/png' });
const uploaded = await client.uploads.uploadFile({
  file: pngBlob,
  fileName: 'generated.png',
  contentType: 'image/png',
  kind: 'image',
});

Caution

Local-path reads (file: './path/to/file') use node:fs/promises and throw in browser environments. Pass a Uint8Array or Blob for browser or non-Node contexts.

---

UploadFileInput

The accepted upload input forms:

type UploadFileInput = string | Uint8Array | Blob;

Form	Description
string	A local file path. Read from disk via node:fs/promises. Node.js only — throws in browsers.
Uint8Array	Raw bytes. Buffer is a Uint8Array and works here too.
Blob / File	Browser-native, or Node ≥ 18 via fs.openAsBlob() / constructors.

---

UploadWaitOptions

Options for upload.wait():

interface UploadWaitOptions {
  intervalMs?: number; // Default: 2000
  timeoutMs?: number;  // Default: 300000
}

Name	Type	Default	Description
intervalMs?	number	2000	Polling interval in milliseconds.
timeoutMs?	number	300000	Maximum wait time in milliseconds. Throws if exceeded.