Class: Imagekitio::Models::FileUploadParams

Inherits:
Internal::Type::BaseModel show all
Extended by:
Internal::Type::RequestParameters::Converter
Includes:
Internal::Type::RequestParameters
Defined in:
lib/imagekitio/models/file_upload_params.rb

Overview

See Also:

Defined Under Namespace

Modules: ResponseField Classes: Transformation

Instance Attribute Summary collapse

Attributes included from Internal::Type::RequestParameters

#request_options

Class Method Summary collapse

Methods included from Internal::Type::RequestParameters::Converter

dump_request

Methods included from Internal::Type::RequestParameters

included

Methods inherited from Internal::Type::BaseModel

#==, ==, #[], coerce, #deconstruct_keys, #deep_to_h, dump, fields, hash, #hash, inherited, #initialize, inspect, #inspect, known_fields, optional, recursively_to_h, required, #to_h, #to_json, #to_s, to_sorbet_type, #to_yaml

Methods included from Internal::Type::Converter

#coerce, coerce, #dump, dump, inspect, #inspect, meta_info, new_coerce_state, type_info

Methods included from Internal::Util::SorbetRuntimeSupport

#const_missing, #define_sorbet_constant!, #sorbet_constant_defined?, #to_sorbet_type, to_sorbet_type

Constructor Details

This class inherits a constructor from Imagekitio::Internal::Type::BaseModel

Instance Attribute Details

#checks ⇒ String?

Server-side checks to run on the asset. Read more about [Upload API checks](/docs/api-reference/upload-file/upload-file#upload-api-checks).



115
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 115

optional :checks, String

#custom_coordinates ⇒ String?

Define an important area in the image. This is only relevant for image type files.

  • To be passed as a string with the x and y coordinates of the top-left corner, and width and height of the area of interest in the format ‘x,y,width,height`. For example - `10,10,100,100`

  • Can be used with fo-customtransformation.

  • If this field is not specified and the file is overwritten, then customCoordinates will be removed.



129
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 129

optional :custom_coordinates, String, api_name: :customCoordinates

#custom_metadata ⇒ Hash{Symbol=>Object}?

JSON key-value pairs to associate with the asset. Create the custom metadata fields before setting these values.



136
137
138
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 136

optional :custom_metadata,
Imagekitio::Internal::Type::HashOf[Imagekitio::Internal::Type::Unknown],
api_name: :customMetadata

#description ⇒ String?

Optional text to describe the contents of the file.



144
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 144

optional :description, String

#expire ⇒ Integer?

The time until your signature is valid. It must be a [Unix time](en.wikipedia.org/wiki/Unix_time) in less than 1 hour into the future. It should be in seconds. This field is only required for authentication when uploading a file from the client side.



153
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 153

optional :expire, Integer

#extensions ⇒ Array<Imagekitio::Models::ExtensionItem::RemoveBg, Imagekitio::Models::ExtensionItem::AIAutoDescription, Imagekitio::Models::ExtensionItem::AutoTaggingExtension>?

Array of extensions to be applied to the asset. Each extension can be configured with specific parameters based on the extension type.



160
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 160

optional :extensions, -> { Imagekitio::Internal::Type::ArrayOf[union: Imagekitio::ExtensionItem] }

#file ⇒ Pathname, ...

The API accepts any of the following:

  • **Binary data** – send the raw bytes as ‘multipart/form-data`.

  • **HTTP / HTTPS URL** – a publicly reachable URL that ImageKit’s servers can fetch.

  • **Base64 string** – the file encoded as a Base64 data URI or plain Base64.

When supplying a URL, the server must receive the response headers within 8 seconds; otherwise the request fails with 400 Bad Request.



84
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 84

required :file, Imagekitio::Internal::Type::FileInput

#file_name ⇒ String

The name with which the file has to be uploaded. The file name can contain:

  • Alphanumeric Characters: ‘a-z`, `A-Z`, `0-9`.

  • Special Characters: ‘.`, `-`

Any other character including space will be replaced by ‘_`



95
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 95

required :file_name, String, api_name: :fileName

#folder ⇒ String?

The folder path in which the image has to be uploaded. If the folder(s) didn’t exist before, a new folder(s) is created.

The folder name can contain:

  • Alphanumeric Characters: ‘a-z` , `A-Z` , `0-9`

  • Special Characters: ‘/` , `_` , `-`

Using multiple ‘/` creates a nested folder.



174
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 174

optional :folder, String

#is_private_file ⇒ Boolean?

Whether to mark the file as private or not.

If ‘true`, the file is marked as private and is accessible only using named transformation or signed URL.



183
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 183

optional :is_private_file, Imagekitio::Internal::Type::Boolean, api_name: :isPrivateFile

#is_published ⇒ Boolean?

Whether to upload file as published or not.

If ‘false`, the file is marked as unpublished, which restricts access to the file only via the media library. Files in draft or unpublished state can only be publicly accessed after being published.

The option to upload in draft state is only available in custom enterprise pricing plans.



196
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 196

optional :is_published, Imagekitio::Internal::Type::Boolean, api_name: :isPublished

#overwrite_ai_tags ⇒ Boolean?

If set to ‘true` and a file already exists at the exact location, its AITags will be removed. Set `overwriteAITags` to `false` to preserve AITags.



203
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 203

optional :overwrite_ai_tags, Imagekitio::Internal::Type::Boolean, api_name: :overwriteAITags

#overwrite_custom_metadata ⇒ Boolean?

If the request does not have ‘customMetadata`, and a file already exists at the exact location, existing customMetadata will be removed.



210
211
212
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 210

optional :overwrite_custom_metadata,
Imagekitio::Internal::Type::Boolean,
api_name: :overwriteCustomMetadata

#overwrite_file ⇒ Boolean?

If ‘false` and `useUniqueFileName` is also `false`, and a file already exists at the exact location, upload API will return an error immediately.



219
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 219

optional :overwrite_file, Imagekitio::Internal::Type::Boolean, api_name: :overwriteFile

#overwrite_tags ⇒ Boolean?

If the request does not have ‘tags`, and a file already exists at the exact location, existing tags will be removed.



226
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 226

optional :overwrite_tags, Imagekitio::Internal::Type::Boolean, api_name: :overwriteTags

#public_key ⇒ String?

Your ImageKit.io public key. This field is only required for authentication when uploading a file from the client side.



233
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 233

optional :public_key, String, api_name: :publicKey

#response_fields ⇒ Array<Symbol, Imagekitio::Models::FileUploadParams::ResponseField>?

Array of response field keys to include in the API response body.



239
240
241
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 239

optional :response_fields,
-> { Imagekitio::Internal::Type::ArrayOf[enum: Imagekitio::FileUploadParams::ResponseField] },
api_name: :responseFields

#signature ⇒ String?

HMAC-SHA1 digest of the token+expire using your ImageKit.io private API key as a key. Learn how to create a signature on the page below. This should be in lowercase.

Signature must be calculated on the server-side. This field is only required for authentication when uploading a file from the client side.



252
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 252

optional :signature, String

#tags ⇒ Array<String>?

Set the tags while uploading the file. Provide an array of tag strings (e.g. ‘[“tag1”, “tag2”, “tag3”]`). The combined length of all tag characters must not exceed 500, and the `%` character is not allowed. If this field is not specified and the file is overwritten, the existing tags will be removed.




# File 'lib/imagekitio/models/file_upload_params.rb', line 261

#token ⇒ String?

A unique value that the ImageKit.io server will use to recognize and prevent subsequent retries for the same request. We suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. This field is only required for authentication when uploading a file from the client side.

Note: Sending a value that has been used in the past will result in a validation error. Even if your previous request resulted in an error, you should always send a new value for this field.



108
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 108

optional :token, String

#transformation ⇒ Imagekitio::Models::FileUploadParams::Transformation?

Configure pre-processing (‘pre`) and post-processing (`post`) transformations.

  • ‘pre` — applied before the file is uploaded to the Media Library. Useful for reducing file size or applying basic optimizations upfront (e.g., resize, compress).

  • ‘post` — applied immediately after upload. Ideal for generating transformed versions (like video encodes or thumbnails) in advance, so they’re ready for delivery without delay.

You can mix and match any combination of post-processing types.



277
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 277

optional :transformation, -> { Imagekitio::FileUploadParams::Transformation }

#use_unique_file_name ⇒ Boolean?

Whether to use a unique filename for this file or not.

If ‘true`, ImageKit.io will add a unique suffix to the filename parameter to get a unique filename.

If ‘false`, then the image is uploaded with the provided filename parameter, and any existing file with the same name is replaced.



289
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 289

optional :use_unique_file_name, Imagekitio::Internal::Type::Boolean, api_name: :useUniqueFileName

#webhook_url ⇒ String?

The final status of extensions after they have completed execution will be delivered to this endpoint as a POST request. [Learn more](/docs/api-reference/digital-asset-management-dam/managing-assets/update-file-details#webhook-payload-structure) about the webhook payload structure.



298
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 298

optional :webhook_url, String, api_name: :webhookUrl

Class Method Details

.dump_request(params) ⇒ Array(Object, Hash{Symbol=>Object})

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Serialize upload options to handle proper formatting for ImageKit backend API. Special cases handled:

  • tags: converted to comma-separated string

  • responseFields: converted to comma-separated string

  • extensions: JSON stringified

  • customMetadata: JSON stringified

  • transformation: JSON stringified



23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 23

def self.dump_request(params)
  state = {can_retry: true}
  case (dumped = dump(params, state: state))
  in Hash
    serialized = serialize_upload_options(dumped)
    options = Imagekitio::Internal::Util.coerce_hash!(serialized[:request_options]).to_h
    request_options = state.fetch(:can_retry) ? options : {**options, max_retries: 0}
    [serialized.except(:request_options), request_options]
  else
    [dumped, nil]
  end
end

.serialize_upload_options(upload_options) ⇒ Hash{Symbol=>Object}

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/imagekitio/models/file_upload_params.rb', line 41

def self.serialize_upload_options(upload_options)
  serialized = {}

  upload_options.each do |key, value|
    # Skip nil values
    if value.nil?
      serialized[key] = value
      next
    end

    serialized[key] = case key
                      when :tags, :responseFields
                        # Tags and response fields should be comma-separated strings
                        value.is_a?(Array) ? value.join(",") : value
                      when :extensions
                        # Extensions should be JSON stringified
                        value.is_a?(Array) ? JSON.generate(value) : value
                      when :customMetadata
                        # Custom metadata should be JSON stringified
                        value.is_a?(Hash) ? JSON.generate(value) : value
                      when :transformation
                        # Transformation should be JSON stringified
                        value.is_a?(Hash) || value.respond_to?(:to_h) ? JSON.generate(value) : value
                      else
                        value
    end
  end

  serialized
end

.values ⇒ Array<Symbol> 




# File 'lib/imagekitio/models/file_upload_params.rb', line 364