ProcessFile

Your account ID.

This is visible on the settings page:

https://www.bytescale.com/dashboard/settings

Example: "A623uY2"

Type: String

Length: 7

Absolute path to a file. Begins with a /.

Example: "/uploads/image.jpg"

Type: String

Min Length: 1

Max Length: 512

The name of the File Processing API (e.g. image, video, audio) or transformation preset (created in the Bytescale Dashboard) to use when processing the file.

Example: "image"

Type: String

Min Length: 1

Max Length: 100

Each File Processing API requires additional query string parameters to specify the desired transformation behavior.

For details, refer to the relevant documentation:

•https://www.bytescale.com/docs/image-processing-api

•https://www.bytescale.com/docs/video-processing-api

•https://www.bytescale.com/docs/audio-processing-api

•https://www.bytescale.com/docs/archive-processing-api

•https://www.bytescale.com/docs/antivirus-api

Type: TransformationParams

Some transformations output multiple files, called artifacts.

You can download each individual transformation artifact by specifying its path with this parameter

Example: "/example/video/part-a.ts"

Type: String

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 or v parameter and to increment it each time you require an updated result.

Default: true

Type: Boolean

Only serve transformations from the cache; do not perform new transformations on cache miss.

If true, then if the transformation result does not exist in the cache, a 404 will be returned. No transformations will be performed.

If false, then if the transformation result does not exist in the cache, a new transformation will be performed to produce the result.

Default: false

Type: Boolean

Specifies whether to cache the transformed result in the Bytescale 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 500ms 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 Bytescale CDN's edge cache or perma-cache, so will have minimal latency.

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

Type: String

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

Specifies the maximum amount of time, in seconds, the transformed result will be cached on the user's device and in the Bytescale 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 Bytescale Dashboard.

Type: Number

Specifies the maximum amount of time, in seconds, that 404 responses will be cached in the Bytescale CDN's edge cache.

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

Type: Number

Forces the browser to display a download prompt for the file, instead of displaying the file in the browser.

When set to true, the Bytescale CDN will add a content-disposition: attachment header to the HTTP response.

Example: true

Type: Boolean

Carries the encrypted payload for an Encrypted URL: these are URLs where the query string portion of the URL has been encrypted using an API key. The query string cannot be read or modified without the API key used to encrypt the URL. When the request is received, Bytescale decrypts the query string and authorizes access using the current permissions of the API key.

This lets you securely grant access to private files via URLs (without requiring Authorization or Cookie headers).

See: Encrypted URLs

Example: "1.BMCyGyFk.6Kfhg5wI8t9AOaY1.tP2Q5uCTvhtefYNPjP7_wxv2mcWI65vLv4"

Type: String

Expires the URL at the given Unix epoch timestamp.

The value can be provided in either milliseconds or seconds since January 1, 1970, 00:00:00 UTC.

Must less than 7 days in the future.

See: Expiring URLs

Example: "1748005508"

Type: Number

Attaches custom metadata to the URL without affecting CDN cacheability or generating unique transformations.

To include metadata, add query string parameters that begin with meta-.

Example: ?meta-user=123&meta-product=abc

When the URL is processed, all meta-* parameters are automatically stripped before transformation or caching occurs. This ensures that variations in metadata do not result in new transformations.

Example: "user-id-123"

Type: String

Allows you to optionally specify the file path of the requested file via the query string instead of the URL path. When provided, the path query string parameter takes precedence and overrides any file path included in the URL path.

This is especially useful with Encrypted URLs, which only encrypt the query string portion of the URL. By placing the file path in the query string using the path parameter, you ensure the location of the file is hidden and protected from tampering.

Must start with a "/".

Example: "/example/image.jpg"

Type: String

Carries the signature for a Signed URL: these are URLs that have been signed using an API key. This signature ensures the URL cannot be modified. When the request is received, Bytescale verifies the signature and authorizes access using the current permissions of the API key.

This lets you securely grant access to private files via URLs (without requiring Authorization or Cookie headers).

See: Signed URLs

Example: "1.W2Sxdk7S.tbORdGfI3afWZAy79r6ivu7O6FnHei_bNZSB9MANIbU"

Type: String

Add this parameter and increment its value to force the file to be reprocessed.

The Bytescale CDN caches files based on the full URL (including the querystring), meaning this parameter is useful when dealing with changes made to transformation presets. By contrast, File Processing 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

Add one of these Authorization header values to your request:

•Option 1: prefix "Bearer " to your API key. The result is your Authorization header value.

•Option 2: use HTTP basic authorization with apikey as your username and your API key as your password.

For advanced options, please see:

https://www.bytescale.com/docs/auth

Type: String