Data Types

ProcessFileParams

Parameter object passed to the ProcessFile method in the Upload SDKs.

Structure

{
"accountId": String,
"artifact": String,
"cache": Boolean,
"cache_perm": String,
"cache_ttl": Number,
"filePath": String,
"large": Boolean,
"version": String
}

Example

{
"accountId": "YOUR_ACCOUNT_ID",
"artifact": "/example/video/part-a.ts",
"cache": true,
"cache_perm": "auto",
"cache_ttl": 31536000,
"filePath": "/uploads/image.jpg",
"large": false,
"transformation": "thumbnail",
"version": "1"
}

Properties

accountId

Your account ID.

This is visible on the settings page:

https://upload.io/dashboard/settings

Example: "A623uY2"

Type: String

Length: 7

Required: No

artifact

Path to an artifact generated by the transformation.

All image transformations output the transformed image to the "/" artifact. Video transformations may output multiple artifacts.

Default: "/"

Type: String

Required: No

cache

Specifies whether to cache the transformed result.

If set to false the transformation will be executed on every request.

Recommendation: instead of disabling the cache, a more performant solution is to use the version parameter and to increment it each time you require an updated result.

Default: true

Type: Boolean

Required: No

cache_perm

Specifies whether to cache the transformed result in the Upload CDN perma-cache.

Perma-caching works by storing your file permanently, or until a manual cache purge is performed.

When cache=false this parameter is automatically set to false.

When cache_perm=auto the perma-cache will only be used for files that take more than 1000ms to process.

When the perma-cache is used, approximately 200ms of latency is added to the initial request. Thereafter, files will be served from the Upload CDN's edge cache or perma-cache, so will have minimal latency.

Default: Please refer to your account's default cache settings in the Upload Dashboard.

Type: String

Allowed Values: "auto", "false", "true"

Required: No

cache_ttl

Specifies the maximum amount of time, in seconds, the transformed result will be cached on the user's device and in the Upload CDN's edge cache.

If the file is perma-cached, then the file will not be reprocessed on edge cache misses.

If the file is not perma-cached, then the file will be reprocessed on edge cache misses.

For more information on perma-caching, see: cache_perm

Default: Please refer to your account's default cache settings in the Upload Dashboard.

Type: Number

Required: No

filePath

Absolute path to a file. Begins with a /.

Example: "/uploads/image.jpg"

Type: String

Min Length: 1

Max Length: 512

Required: No

large

Set to true to return transformed files over 6MB in the initial HTTP response.

By default, transformations that produce files larger than 6MB require a subsequent HTTP request to return the result: the initial HTTP request will process the file and return a JSON result instructing the requester the transformation has been performed. All subsequent requests will return the transformed file. Enable this flag to ensure the transformed file is always returned in the initial response.

Recommendation: set large=true only if you require transformation results over 6MB. A small amount of latency is incurred on edge cache misses when this flag is enabled. In general, we recommend adjusting your transformation parameters to keep files below this size, instead of enabling this flag.

Default: false

Type: Boolean

Required: No

transformation

Transformation URL slug.

These are created in the Upload Dashboard:

https://upload.io/dashboard/transformations

Example: "thumbnail"

Type: String

Min Length: 1

Max Length: 100

Required: No

version

Add this parameter and increment its value to force the reprocessing of a file.

The Upload CDN caches based on the full URL (including the querystring), meaning this parameter is useful when dealing with changes made to transformation presets. By contrast, transformation APIs (like the Image Processing API) shouldn't ever require this parameter, since the URL/querystring naturally changes each time you adjust a parameter, causing a cache miss and the file to be reprocessed with the new querystring parameters.

The value of the version parameter can be anything, e.g. an incremental number, a timestamp, etc.

You only need to provide and update this value if/when you make changes to a transformation preset's settings.

Example: "1"

Type: String

Required: No

Was this section helpful? Yes No

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported: