{"id":13879808,"url":"https://github.com/uploadcare/uploadcare-ruby","last_synced_at":"2025-04-12T18:42:31.669Z","repository":{"id":11689696,"uuid":"14201371","full_name":"uploadcare/uploadcare-ruby","owner":"uploadcare","description":"Ruby API client that handles uploads and further operations with files by wrapping Uploadcare Upload and REST APIs.","archived":false,"fork":false,"pushed_at":"2025-04-01T12:11:49.000Z","size":1223,"stargazers_count":39,"open_issues_count":5,"forks_count":28,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-04T15:22:08.678Z","etag":null,"topics":["api","client","file-upload","image-processing","image-recognition","image-upload","processing","ruby","sdk","upload","uploadcare","uploader"],"latest_commit_sha":null,"homepage":"https://uploadcare.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uploadcare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-11-07T10:56:04.000Z","updated_at":"2025-04-01T11:32:51.000Z","dependencies_parsed_at":"2024-04-19T20:43:06.594Z","dependency_job_id":"0056e511-4e69-4fa5-bee6-a4b81f0b400e","html_url":"https://github.com/uploadcare/uploadcare-ruby","commit_stats":{"total_commits":197,"total_committers":16,"mean_commits":12.3125,"dds":"0.40609137055837563","last_synced_commit":"08e1e1db239a34476dd34d26577340dcc4987e18"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fuploadcare-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fuploadcare-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fuploadcare-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fuploadcare-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uploadcare","download_url":"https://codeload.github.com/uploadcare/uploadcare-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248617112,"owners_count":21134190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","file-upload","image-processing","image-recognition","image-upload","processing","ruby","sdk","upload","uploadcare","uploader"],"created_at":"2024-08-06T08:02:34.131Z","updated_at":"2025-04-12T18:42:31.644Z","avatar_url":"https://github.com/uploadcare.png","language":"Ruby","readme":"# Ruby integration for Uploadcare\n\n![license](https://img.shields.io/badge/license-MIT-brightgreen.svg)\n[![Build Status][actions-img]][actions-badge]\n[![Uploadcare stack on StackShare][stack-img]][stack]\n\n[actions-badge]: https://github.com/uploadcare/uploadcare-ruby/actions/workflows/ruby.yml\n[actions-img]: https://github.com/uploadcare/uploadcare-ruby/actions/workflows/ruby.yml/badge.svg\n[coverals-img]: https://coveralls.io/repos/github/uploadcare/uploadcare-ruby/badge.svg?branch=main\n[coverals]: https://coveralls.io/github/uploadcare/uploadcare-ruby?branch=main\n[stack-img]: https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat\n[stack]: https://stackshare.io/uploadcare/stacks/\n\nUploadcare Ruby integration handles uploads and further operations with files by\nwrapping Upload and REST APIs.\n\n* [Installation](#installation)\n* [Usage](#usage)\n  * [Uploading files](#uploading-files)\n    * [Uploading and storing a single file](#uploading-and-storing-a-single-file)\n    * [Multiple ways to upload files](#multiple-ways-to-upload-files)\n    * [Uploading options](#uploading-options)\n  * [File management](#file-management)\n    * [File](#file)\n    * [FileList](#filelist)\n    * [Pagination](#pagination)\n    * [Custom File Metadata](#custom-file-metadata)\n    * [Group](#group)\n    * [GroupList](#grouplist)\n    * [Webhook](#webhook)\n    * [Add-Ons](#add-ons)\n    * [Project](#project)\n    * [Conversion](#conversion)\n* [Useful links](#useful-links)\n\n## Requirements\n* ruby 3.0+\n\n## Compatibility\n\nNote that `uploadcare-ruby` **3.x** is not backward compatible with\n**[2.x](https://github.com/uploadcare/uploadcare-ruby/tree/v2.x)**.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"uploadcare-ruby\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nYou can also use it outside of Rails or other Apps.\n\nInstall the gem directly:\n\n    $ gem install uploadcare-ruby\n\nThen in your Ruby code:\n\n```ruby\nrequire \"uploadcare\"\n\nUploadcare.config.public_key = \"your_public_key\"\nUploadcare.config.secret_key = \"your_secret_key\"\n\n# Example usage\nuuid = \"file_uuid\"\nputs Uploadcare::File.info(uuid).inspect\n```\n\nIf you use `api_struct` gem in your project, replace it with `uploadcare-api_struct`:\n```ruby\ngem 'uploadcare-api_struct'\n```\nand run `bundle install`\n\nIf already not, create your project in [Uploadcare dashboard](https://app.uploadcare.com/?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=uploadcare-ruby) and copy\nits [API keys](https://app.uploadcare.com/projects/-/api-keys/) from there.\n\nSet your Uploadcare keys in config file or through environment variables:\n```bash\nexport UPLOADCARE_PUBLIC_KEY=your_public_key\nexport UPLOADCARE_SECRET_KEY=your_private_key\n```\n\nOr configure your app yourself if you are using different way of storing keys.\nGem configuration is available in `Uploadcare.configuration`. Full list of\nsettings can be seen in [`lib/uploadcare.rb`](lib/uploadcare.rb)\n\n```ruby\n# your_config_initializer_file.rb\nUploadcare.config.public_key = \"your_public_key\"\nUploadcare.config.secret_key = \"your_private_key\"\n```\n\n## Usage\n\nThis section contains practical usage examples. Please note, everything that\nfollows gets way more clear once you've looked through our\n[docs](https://uploadcare.com/docs/?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=uploadcare-ruby)\nand [Upload](https://uploadcare.com/api-refs/upload-api/) and [REST](https://uploadcare.com/api-refs/rest-api/) API refs.\n\nYou can also find an example project [here](https://github.com/uploadcare/uploadcare-rails-example).\n\n### Uploading files\n#### Uploading and storing a single file\n\nUsing Uploadcare is simple, and here are the basics of handling files.\n\n```ruby\n@file_to_upload = File.open(\"your-file.png\")\n\n@uc_file = Uploadcare::Uploader.upload(@file_to_upload, store: \"auto\")\n\n@uc_file.uuid\n# =\u003e \"dc99200d-9bd6-4b43-bfa9-aa7bfaefca40\"\n\n# URL for the file, can be used with your website or app right away\n@uc_file.original_file_url\n# =\u003e \"https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/your-file.png\"\n```\n\nThe `store` option can have these possible values:\n- `true`: mark the uploaded file as stored.\n- `false`: do not mark the uploaded file as stored and remove it after 24 hours.\n- `\"auto\"`: defers the choice of storage behavior to the [auto-store setting](https://app.uploadcare.com/projects/-/settings/#storage) for your Uploadcare project. This is the default behavior.\n\nYour might then want to store or delete the uploaded file.\n\n```ruby\n# that's how you store a file, if you have uploaded the file using store: false and changed your mind later\n@uc_file.store\n# =\u003e #\u003cUploadcare::Api::File ...\n\n# and that works for deleting it\n@uc_file.delete\n# =\u003e #\u003cUploadcare::Api::File ...\n```\n\n#### Multiple ways to upload files\n\nUploadcare supports multiple ways to upload files:\n\n```ruby\n# Smart upload - detects type of passed object and picks appropriate upload method\n# If you have a large file (more than 100Mb / 10485760 bytes), the uploader will automatically process it with a multipart upload\n\nUploadcare::Uploader.upload(\"https://placekitten.com/96/139\", store: \"auto\")\n```\n\nThere are explicit ways to select upload type:\n\n```ruby\nfiles = [File.open(\"1.jpg\"), File.open(\"1.jpg\")]\nUploadcare::Uploader.upload_files(files, store: 'auto')\n\nUploadcare::Uploader.upload_from_url(\"https://placekitten.com/96/139\", store: \"auto\")\n```\nIt is possible to track progress of the upload-from-URL process. To do that, you should specify the `async` option and get a token:\n\n```ruby\nUploadcare::Uploader.upload_from_url(\"https://placekitten.com/96/139\", async: true)\n# =\u003e \"c6e31082-6bdc-4cb3-bef5-14dd10574d72\"\n```\n\nAfter the request for uploading-from-URL is sent, you can check the progress of the upload by sending the `get_upload_from_url_status` request:\n\n```ruby\nUploadcare::Uploader.get_upload_from_url_status(\"1251ee66-3631-4416-a2fb-96ba59f5a515\")\n# =\u003e Success({:size=\u003e453543, :total=\u003e453543, :done=\u003e453543, :uuid=\u003e\"5c51a7fe-e45d-42a2-ba5e-79957ff4bdab\", :file_id=\u003e\"5c51a7fe-e45d-42a2-ba5e-79957ff4bdab\", :original_filename=\u003e\"2250\", :is_image=\u003etrue, :is_stored=\u003efalse, :image_info=\u003e{:dpi=\u003e[96, 96], :width=\u003e2250, :format=\u003e\"JPEG\", :height=\u003e2250, :sequence=\u003efalse, :color_mode=\u003e\"RGB\", :orientation=\u003enil, :geo_location=\u003enil, :datetime_original=\u003enil}, :video_info=\u003enil, :content_info=\u003e{:mime=\u003e{:mime=\u003e\"image/jpeg\", :type=\u003e\"image\", :subtype=\u003e\"jpeg\"}, :image=\u003e{:dpi=\u003e[96, 96], :width=\u003e2250, :format=\u003e\"JPEG\", :height=\u003e2250, :sequence=\u003efalse, :color_mode=\u003e\"RGB\", :orientation=\u003enil, :geo_location=\u003enil, :datetime_original=\u003enil}}, :is_ready=\u003etrue, :filename=\u003e\"2250\", :mime_type=\u003e\"image/jpeg\", :metadata=\u003e{}, :status=\u003e\"success\"})\n```\n\nIn case of the `async` option is disabled, uploadcare-ruby tries to request the upload status several times (depending on the `max_request_tries` config param) and then returns uploaded file attributes.\n\n```ruby\n# multipart upload - can be useful for files bigger than 10 mb\nUploadcare::Uploader.multipart_upload(File.open(\"big_file.bin\"), store: true)\n```\n\nFor the multipart upload you can pass a block to add some additional logic after each file chunk is uploaded.\nFor example to track file uploading progress you can do something like this:\n\n```ruby\nfile = File.open(\"big_file.bin\")\nprogress = 0\nUploadcare::Uploader.multipart_upload(file, store: true) do |options|\n  progress += (100.0 / options[:links_count])\n  puts \"PROGRESS = #{progress}\"\nend\n```\nOutput of the code above looks like:\n```console\nPROGRESS = 4.545454545454546\nPROGRESS = 9.090909090909092\nPROGRESS = 13.636363636363637\n...\n```\nOptions available in a block:\n- **:chunk_size** - size of each chunk in bytes;\n- **:object** - file object which is going to be uploaded;\n- **:offset** - offset from the beginning of a File object in bytes;\n- **:link_id** - index of a link provided by Uploadcare API. Might be treated as index of a chunk;\n- **:links** - array of links for uploading file's chunks;\n- **:links_count** - count of the array of links.\n\n#### Uploading options\n\nYou can override [auto-store setting](https://app.uploadcare.com/projects/-/settings/#storage) from your Uploadcare project for each upload request:\n\n```ruby\n@api.upload(files, store: true)          # mark the uploaded file as stored.\n@api.upload(files, store: false)         # do not mark the uploaded file as stored and remove it after 24 hours.\n@api.upload_from_url(url, store: \"auto\") # defers the choice of storage behavior to the auto-store setting.\n```\n\nYou can upload file with custom metadata, for example `subsystem` and `pet`:\n\n```ruby\n@api.upload(files, metadata: { subsystem: 'my_subsystem', pet: 'cat' } )\n@api.upload_from_url(url, metadata: { subsystem: 'my_subsystem', pet: 'cat' })\n```\n\n### File management\n\nEntities are representations of objects in Uploadcare cloud.\n\n#### File\n\nFile entity contains its metadata. It also supports `include` param to include additional fields to the file object, such as: \"appdata\".\n\n```ruby\n@file = Uploadcare::File.file(\"FILE_UUID\", include: \"appdata\")\n{\n  \"datetime_removed\"=\u003enil,\n  \"datetime_stored\"=\u003e\"2018-11-26T12:49:10.477888Z\",\n  \"datetime_uploaded\"=\u003e\"2018-11-26T12:49:09.945335Z\",\n  \"is_image\"=\u003etrue,\n  \"is_ready\"=\u003etrue,\n  \"mime_type\"=\u003e\"image/jpeg\",\n  \"original_file_url\"=\u003e\"https://ucarecdn.com/FILE_UUID/pineapple.jpg\",\n  \"original_filename\"=\u003e\"pineapple.jpg\",\n  \"size\"=\u003e642,\n  \"url\"=\u003e\"https://api.uploadcare.com/files/FILE_UUID/\",\n  \"uuid\"=\u003e\"FILE_UUID\",\n  \"variations\"=\u003enil,\n  \"content_info\"=\u003e{\n    \"mime\"=\u003e{\n      \"mime\"=\u003e\"image/jpeg\",\n      \"type\"=\u003e\"image\",\n      \"subtype\"=\u003e\"jpeg\"\n    },\n    \"image\"=\u003e{\n      \"format\"=\u003e\"JPEG\",\n      \"width\"=\u003e500,\n      \"height\"=\u003e500,\n      \"sequence\"=\u003efalse,\n      \"orientation\"=\u003e6,\n      \"geo_location\"=\u003e{\n        \"latitude\"=\u003e55.62013611111111,\n        \"longitude\"=\u003e37.66299166666666\n      },\n      \"datetime_original\"=\u003e\"2018-08-20T08:59:50\",\n      \"dpi\"=\u003e[72, 72]\n    }\n  },\n  \"metadata\"=\u003e{\n    \"subsystem\"=\u003e\"uploader\",\n    \"pet\"=\u003e\"cat\"\n  },\n  \"appdata\"=\u003e{\n    \"uc_clamav_virus_scan\"=\u003e{\n      \"data\"=\u003e{\n        \"infected\"=\u003etrue,\n        \"infected_with\"=\u003e\"Win.Test.EICAR_HDB-1\"\n      },\n      \"version\"=\u003e\"0.104.2\",\n      \"datetime_created\"=\u003e\"2021-09-21T11:24:33.159663Z\",\n      \"datetime_updated\"=\u003e\"2021-09-21T11:24:33.159663Z\"\n    },\n    \"remove_bg\"=\u003e{\n      \"data\"=\u003e{\n        \"foreground_type\"=\u003e\"person\"\n      },\n      \"version\"=\u003e\"1.0\",\n      \"datetime_created\"=\u003e\"2021-07-25T12:24:33.159663Z\",\n      \"datetime_updated\"=\u003e\"2021-07-25T12:24:33.159663Z\"\n    },\n    \"aws_rekognition_detect_labels\"=\u003e{\n      \"data\"=\u003e{\n        \"LabelModelVersion\"=\u003e\"2.0\",\n        \"Labels\"=\u003e[\n          {\n            \"Confidence\"=\u003e93.41645812988281,\n            \"Instances\"=\u003e[],\n            \"Name\"=\u003e\"Home Decor\",\n            \"Parents\"=\u003e[]\n          },\n          {\n            \"Confidence\"=\u003e70.75951385498047,\n            \"Instances\"=\u003e[],\n            \"Name\"=\u003e\"Linen\",\n            \"Parents\"=\u003e[{ \"Name\"=\u003e\"Home Decor\" }]\n          },\n          {\n            \"Confidence\"=\u003e64.7123794555664,\n            \"Instances\"=\u003e[],\n            \"Name\"=\u003e\"Sunlight\",\n            \"Parents\"=\u003e[]\n          },\n          {\n            \"Confidence\"=\u003e56.264793395996094,\n            \"Instances\"=\u003e[],\n            \"Name\"=\u003e\"Flare\",\n            \"Parents\"=\u003e[{ \"Name\"=\u003e\"Light\" }]\n          },\n          {\n            \"Confidence\"=\u003e50.47153854370117,\n            \"Instances\"=\u003e[],\n            \"Name\"=\u003e\"Tree\",\n            \"Parents\"=\u003e[{ \"Name\"=\u003e\"Plant\" }]\n          }\n        ]\n      },\n      \"version\"=\u003e\"2016-06-27\",\n      \"datetime_created\"=\u003e\"2021-09-21T11:25:31.259763Z\",\n      \"datetime_updated\"=\u003e\"2021-09-21T11:27:33.359763Z\"\n    }\n  }\n}\n\n@file.local_copy # copy file to local storage\n\n@file.remote_copy # copy file to remote storage\n\n@file.store # stores file, returns updated metadata\n\n@file.delete #deletes file. Returns updated metadata\n```\n\nThe File object is also can be converted if it is a document or a video file. Imagine, you have a document file:\n\n```ruby\n@file = Uploadcare::File.file(\"FILE_UUID\")\n```\n\nTo convert it to an another file, just do:\n\n```ruby\n@converted_file = @file.convert_document({ format: \"png\", page: \"1\" }, store: true)\n# =\u003e {\n#    \"uuid\"=\u003e\"\u003cNEW_FILE_UUID\u003e\"}\n#    ...other file info...\n# }\n# OR\n# Failure({:\"\u003cFILE_UUID\u003e/document/-/format/png/-/page/1/\"=\u003e\"the target_format is not a supported 'to' format for this source file. \u003cyou_source_file_extension\u003e -\u003e png\"})\n```\n\nSame works for video files:\n\n```ruby\n@converted_file = @file.convert_video(\n  {\n    format: \"ogg\",\n    quality: \"best\",\n    cut: { start_time: \"0:0:0.1\", length: \"end\" },\n    size: { resize_mode: \"change_ratio\", width: \"600\", height: \"400\" },\n    thumb: { N: 1, number: 2 }\n  },\n  store: true\n)\n# =\u003e {\n#    \"uuid\"=\u003e\"\u003cNEW_FILE_UUID\u003e\"}\n#    ...other file info...\n# }\n# OR\n# Failure({:\"\u003cFILE_UUID\u003e/video/-/size/600x400/preserve_ratio/-/quality/best/-/format/ogg/-/cut/0:0:0.1/end/-/thumbs~1/2/\"=\u003e\"CDN Path error: Failed to parse remainder \\\"/preserve_ratio\\\" of \\\"size/600x400/preserve_ratio\\\"\"})\n```\n\nMore about file conversion [here](#conversion).\nMetadata of deleted files is stored permanently.\n\n#### FileList\n\n`Uploadcare::FileList` represents the whole collection of files (or it's\nsubset) and provides a way to iterate through it, making pagination transparent.\nFileList objects can be created using `Uploadcare::FileList.file_list` method.\n\n```ruby\n@list = Uploadcare::FileList.file_list\n# Returns instance of Uploadcare::Entity::FileList\n\u003cHashie::Mash\n  next=nil\n  per_page=100\n  previous=nil\n  results=[\n    # Array of Entity::File\n  ]\n  total=8\u003e\n# load last page of files\n@files = @list.files\n# load all files\n@all_files = @list.load\n```\n\nThis method accepts some options to control which files should be fetched and\nhow they should be fetched:\n\n- **:limit** — Controls page size. Accepts values from 1 to 1000, defaults to 100.\n- **:stored** — Can be either `true` or `false`. When true, file list will contain only stored files. When false — only not stored.\n- **:removed** — Can be either `true` or `false`. When true, file list will contain only removed files. When false — all except removed. Defaults to false.\n- **:ordering** — Controls the order of returned files. Available values: `datetime_uploaded`, `-datetime_uploaded`. Defaults to `datetime_uploaded`. More info can be found [here](https://uploadcare.com/api-refs/rest-api/v0.7.0/#operation/filesList).\n- **:from** — Specifies the starting point for a collection. Resulting collection will contain files from the given value and to the end in a direction set by an **ordering** option. When files are ordered by `datetime_updated` in any direction, accepts either a `DateTime` object or an ISO 8601 string. When files are ordered by size, accepts non-negative integers (size in bytes). More info can be found [here](https://uploadcare.com/api-refs/rest-api/v0.7.0/#operation/filesList).\n\nOptions used to create a file list can be accessed through `#options` method.\nNote that, once set, they don't affect file fetching process anymore and are\nstored just for your convenience. That is why they are frozen.\n\n```ruby\noptions = {\n  limit: 10,\n  stored: true,\n  ordering: \"-datetime_uploaded\",\n  from: \"2017-01-01T00:00:00\",\n}\n@list = @api.file_list(options)\n```\n\nTo simply get all associated objects:\n```ruby\n@list.all # =\u003e returns Array of Files\n```\n\n#### Pagination\n\nInitially, `FileList` is a paginated collection. It can be navigated using following methods:\n```ruby\n  @file_list = Uploadcare::FileList.file_list\n  # Let's assume there are 250 files in cloud. By default, UC loads 100 files. To get next 100 files, do:\n  @next_page = @file_list.next_page\n  # To get previous page:\n  @previous_page = @file_list.previous_page\n```\n\nAlternatively, it's possible to iterate through full list of groups or files with `each`:\n```ruby\n@list.each do |file|\n  p file.url\nend\n```\n\n#### Custom File Metadata\n\nFile metadata is additional, arbitrary data, associated with uploaded file.\nAs an example, you could store unique file identifier from your system.\n\n```ruby\n# Get file's metadata keys and values.\nUploadcare::FileMetadata.index('FILE_UUID')\n\n# Get the value of a single metadata key.\nUploadcare::FileMetadata.show('FILE_UUID', 'KEY')\n\n# Update the value of a single metadata key. If the key does not exist, it will be created.\nUploadcare::FileMetadata.update('FILE_UUID', 'KEY', 'VALUE')\n\n# Delete a file's metadata key.\nUploadcare::FileMetadata.delete('FILE_UUID', 'KEY')\n```\n\n#### Group\n\nGroups are structures intended to organize sets of separate files. Each group is\nassigned UUID. Note, group UUIDs include a `~#{files_count}` part at the end.\nThat's a requirement of our API.\n\n```ruby\n# group can be created from an array of Uploadcare files (UUIDs)\n@file = \"134dc30c-093e-4f48-a5b9-966fe9cb1d01\"\n@file2 = \"134dc30c-093e-4f48-a5b9-966fe9cb1d02\"\n@files_ary = [@file, @file2]\n@group = Uploadcare::Group.create @files\n\n# group can be stored by group ID. It means that all files of a group will be stored on Uploadcare servers permanently\nUploadcare::Group.store(group.id)\n\n# get a file group by its ID.\nUploadcare::Group.rest_info(group.id)\n\n# group can be deleted by group ID.\nUploadcare::Group.delete(group.id)\n# Note: This operation only removes the group object itself. All the files that were part of the group are left as is.\n```\n\n#### GroupList\n`GroupList` is a list of `Group`\n\n```ruby\n@group_list = Uploadcare::GroupList.list\n# To get an array of groups:\n@groups = @group_list.all\n```\n\nThis is a paginated list, so [pagination](#Pagination) methods apply\n\n#### Webhook\nhttps://uploadcare.com/docs/api_reference/rest/webhooks/\n\nYou can use webhooks to provide notifications about your uploads to target urls.\nThis gem lets you create and manage webhooks.\n\nEach webhook payload can be signed with a secret (the `signing_secret` option) to ensure that the request comes from the expected sender.\nMore info about secure webhooks [here](https://uploadcare.com/docs/security/secure-webhooks/).\n\n```ruby\nUploadcare::Webhook.create(target_url: \"https://example.com/listen\", event: \"file.uploaded\", is_active: true, signing_secret: \"some-secret\")\nUploadcare::Webhook.update(\u003cwebhook_id\u003e, target_url: \"https://newexample.com/listen/new\", event: \"file.uploaded\", is_active: true, signing_secret: \"some-secret\")\nUploadcare::Webhook.delete(\"https://example.com/listen\")\nUploadcare::Webhook.list\n```\n\n##### Webhook signature verification\n\nThe gem has a helper class to verify a webhook signature from headers —\n`Uploadcare::Param::WebhookSignatureVerifier`. This class accepts three\nimportant options:\n\n- **:webhook_body** — this option represents parameters received in the webhook\n  request in the JSON format.\n  **NOTE**: if you're using Rails, you should exclude options `controller`,\n  `action` and `post` from the `webhook_body`.\n- **:signing_secret** — the secret that was set while creating/updating a\n  webhook. This option can be specified as an ENV var with the name\n  `UC_SIGNING_SECRET` — then no need to send it to the verifier class.\n- **:x_uc_signature_header** — the content of the `X-Uc-Signature` HTTP header\n  in the webhook request.\n\nUsing the `Uploadcare::Param::WebhookSignatureVerifier` class example:\n\n```ruby\n  webhook_body = '{...}'\n\nsigning_secret = \"12345X\"\nx_uc_signature_header = \"v1=9b31c7dd83fdbf4a2e12b19d7f2b9d87d547672a325b9492457292db4f513c70\"\n\nUploadcare::Param::WebhookSignatureVerifier.valid?(signing_secret: signing_secret, x_uc_signature_header: x_uc_signature_header, webhook_body: webhook_body)\n```\n\nYou can write your verifier. Example code:\n\n```ruby\nwebhook_body_json = '{...}'\n\nsigning_secret = ENV['UC_SIGNING_SECRET']\nx_uc_signature_header = \"v1=f4d859ed2fe47b9a4fcc81693d34e58ad12366a841e58a7072c1530483689cc0\"\n\ndigest = OpenSSL::Digest.new('sha256')\n\ncalculated_signature = \"v1=#{OpenSSL::HMAC.hexdigest(digest, signing_secret.force_encoding(\"utf-8\"), webhook_body_json.force_encoding(\"utf-8\"))}\"\n\nif calculated_signature == x_uc_signature_header\n  puts \"WebHook signature matches!\"\nelse\n  puts \"WebHook signature mismatch!\"\nend\n```\n\n#### Add-Ons\n\nAn `Add-On` is an application implemented by Uploadcare that accepts uploaded files as an input and can produce other files and/or appdata as an output.\n\n##### AWS Rekognition\n\n```ruby\n# Execute AWS Rekognition Add-On for a given target to detect labels in an image.\n# Note: Detected labels are stored in the file's appdata.\nUploadcare::Addons.ws_rekognition_detect_labels('FILE_UUID')\n\n# Check the status of AWS Rekognition.\nUploadcare::Addons.ws_rekognition_detect_labels_status('RETURNED_ID_FROM_WS_REKOGNITION_DETECT_LABELS')\n```\n\n##### AWS Rekognition Moderation\n\n```ruby\n# Execute AWS Rekognition Moderation Add-On for a given target to detect moderation labels in an image.\n# Note: Detected moderation labels are stored in the file's appdata.\n\nUploadcare::Addons.ws_rekognition_detect_moderation_labels('FILE_UUID')\n\n# Check the status of an Add-On execution request that had been started using the Execute Add-On operation.\nUploadcare::Addons.ws_rekognition_detect_moderation_labels_status('RETURNED_ID_FROM_WS_REKOGNITION_DETECT_MODERATION_LABELS')\n```\n\n##### ClamAV\n\n```ruby\n# ClamAV virus checking Add-On for a given target.\nUploadcare::Addons.uc_clamav_virus_scan('FILE_UUID')\n\n# Check and purge infected file.\nUploadcare::Addons.uc_clamav_virus_scan('FILE_UUID', purge_infected: true )\n\n# Check the status of an Add-On execution request that had been started using the Execute Add-On operation.\nUploadcare::Addons.uc_clamav_virus_scan_status('RETURNED_ID_FROM_UC_CLAMAV_VIRUS_SCAN')\n```\n\n##### Remove.bg\n\n```ruby\n# Execute remove.bg background image removal Add-On for a given target.\nUploadcare::Addons.remove_bg('FILE_UUID')\n\n# You can pass optional parameters.\n# See the full list of parameters here: https://uploadcare.com/api-refs/rest-api/v0.7.0/#operation/removeBgExecute\nUploadcare::Addons.remove_bg('FILE_UUID', crop: true, type_level: '2')\n\n# Check the status of an Add-On execution request that had been started using the Execute Add-On operation.\nUploadcare::Addons.remove_bg_status('RETURNED_ID_FROM_REMOVE_BG')\n```\n\n#### Project\n\n`Project` provides basic info about the connected Uploadcare project. That\nobject is also an Hashie::Mash, so every methods out of\n[these](https://uploadcare.com/api-refs/rest-api/v0.7.0/#operation/projectInfo) will work.\n\n```ruby\n@project = Uploadcare::Project.project\n# =\u003e #\u003cUploadcare::Api::Project collaborators=[], name=\"demo\", pub_key=\"your_public_key\", autostore_enabled=true\u003e\n\n@project.name\n# =\u003e \"demo\"\n\n@project.collaborators\n# =\u003e []\n# while that one was empty, it usually goes like this:\n# [{\"email\": collaborator@gmail.com, \"name\": \"Collaborator\"}, {\"email\": collaborator@gmail.com, \"name\": \"Collaborator\"}]\n```\n\n#### Conversion\n\n##### Video\n\nAfter each video file upload you obtain a file identifier in UUID format.\nThen you can use this file identifier to convert your video in multiple ways:\n\n```ruby\nUploadcare::VideoConverter.convert(\n  [\n    {\n      uuid: \"dc99200d-9bd6-4b43-bfa9-aa7bfaefca40\",\n      size: { resize_mode: \"change_ratio\", width: \"600\", height: \"400\" },\n      quality: \"best\",\n      format: \"ogg\",\n      cut: { start_time: \"0:0:0.0\", length: \"0:0:1.0\" },\n      thumbs: { N: 2, number: 1 }\n    }\n  ],\n  store: false\n)\n```\nThis method accepts options to set properties of an output file:\n\n- **uuid** — the file UUID-identifier.\n- **size**:\n  - **resize_mode** - size operation to apply to a video file. Can be `preserve_ratio (default)`, `change_ratio`, `scale_crop` or `add_padding`.\n  - **width** - width for a converted video.\n  - **height** - height for a converted video.\n\n```\n  NOTE: you can choose to provide a single dimension (width OR height).\n        The value you specify for any of the dimensions should be a non-zero integer divisible by 4\n```\n\n- **quality** - sets the level of video quality that affects file sizes and hence loading times and volumes of generated traffic. Can be `normal (default)`, `better`, `best`, `lighter`, `lightest`.\n- **format** - format for a converted video. Can be `mp4 (default)`, `webm`, `ogg`.\n- **cut**:\n  - **start_time** - defines the starting point of a fragment to cut based on your input file timeline.\n  - **length** - defines the duration of that fragment.\n- **thumbs**:\n  - **N** - quantity of thumbnails for your video - non-zero integer ranging from 1 to 50; defaults to 1.\n  - **number** - zero-based index of a particular thumbnail in a created set, ranging from 1 to (N - 1).\n- **store** - a flag indicating if Uploadcare should store your transformed outputs.\n\n```ruby\n# Response\n{\n  :result =\u003e [\n    {\n      :original_source=\u003e\"dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/video/-/size/600x400/change_ratio/-/quality/best/-/format/ogg/-/cut/0:0:0.0/0:0:1.0/-/thumbs~2/1/\",\n      :token=\u003e911933811,\n      :uuid=\u003e\"6f9b88bd-625c-4d60-bfde-145fa3813d95\",\n      :thumbnails_group_uuid=\u003e\"cf34c5a1-8fcc-4db2-9ec5-62c389e84468~2\"\n    }\n  ],\n  :problems=\u003e{}\n}\n```\nParams in the response:\n- **result** - info related to your transformed output(-s):\n  - **original_source** - built path for a particular video with all the conversion operations and parameters.\n  - **token** - a processing job token that can be used to get a [job status](https://uploadcare.com/docs/transformations/video-encoding/#status) (see below).\n  - **uuid** - UUID of your processed video file.\n  - **thumbnails_group_uuid** - holds :uuid-thumb-group, a UUID of a [file group](https://uploadcare.com/api-refs/rest-api/v0.7.0/#operation/groupsList) with thumbnails for an output video, based on the thumbs [operation](https://uploadcare.com/docs/transformations/video-encoding/#operation-thumbs) parameters.\n- **problems** - problems related to your processing job, if any.\n\nTo convert multiple videos just add params as a hash for each video to the first argument of the `Uploadcare::VideoConverter#convert` method:\n\n```ruby\nUploadcare::VideoConverter.convert(\n  [\n    { video_one_params }, { video_two_params }, ...\n  ],\n  store: false\n)\n```\n\n\nTo check a status of a video processing job you can simply use appropriate method of `Uploadcare::VideoConverter`:\n\n```ruby\ntoken = 911933811\nUploadcare::VideoConverter.status(token)\n```\n`token` here is a processing job token, obtained in a response of a convert video request.\n\n```ruby\n# Response\n{\n  :status =\u003e \"finished\",\n  :error =\u003e nil,\n  :result =\u003e {\n    :uuid =\u003e \"dc99200d-9bd6-4b43-bfa9-aa7bfaefca40\",\n    :thumbnails_group_uuid =\u003e \"0f181f24-7551-42e5-bebc-14b15d9d3838~2\"\n  }\n}\n```\n\nParams in the response:\n- **status** - processing job status, can have one of the following values:\n  - *pending* — video file is being prepared for conversion.\n  - *processing* — video file processing is in progress.\n  - *finished* — the processing is finished.\n  - *failed* — we failed to process the video, see error for details.\n  - *canceled* — video processing was canceled.\n- **error** - holds a processing error if we failed to handle your video.\n- **result** - repeats the contents of your processing output.\n- **thumbnails_group_uuid** - holds :uuid-thumb-group, a UUID of a file group with thumbnails for an output video, based on the thumbs operation parameters.\n- **uuid** - a UUID of your processed video file.\n\nMore examples and options can be found [here](https://uploadcare.com/docs/transformations/video-encoding/#video-encoding).\n\n##### Document\n\nAfter each document file upload you obtain a file identifier in UUID format.\n\nYou can use file identifier to determine the document format and possible conversion formats.\n```ruby\nUploadcare::DocumentConverter.info(\"dc99200d-9bd6-4b43-bfa9-aa7bfaefca40\")\n\n# Response\n{:error=\u003enil, :format=\u003e{\n  :name=\u003e\"jpg\",\n  :conversion_formats=\u003e[\n    {:name=\u003e\"avif\"}, {:name=\u003e\"bmp\"}, {:name=\u003e\"gif\"}, {:name=\u003e\"ico\"}, {:name=\u003e\"pcx\"}, {:name=\u003e\"pdf\"}, {:name=\u003e\"png\"}, {:name=\u003e\"ps\"}, {:name=\u003e\"svg\"}, {:name=\u003e\"tga\"}, {:name=\u003e\"thumbnail\"}, {:name=\u003e\"tiff\"}, {:name=\u003e\"wbmp\"}, {:name=\u003e\"webp\"}\n  ]\n}}\n```\n\nThen you can use this file identifier to convert your document to a new format:\n\n```ruby\nUploadcare::DocumentConverter.convert(\n  [\n    {\n      uuid: \"dc99200d-9bd6-4b43-bfa9-aa7bfaefca40\",\n      format: \"pdf\"\n    }\n  ],\n  store: false\n)\n```\nor create an image of a particular page (if using image format):\n```ruby\nUploadcare::DocumentConverter.convert(\n  [\n    {\n      uuid: \"a4b9db2f-1591-4f4c-8f68-94018924525d\",\n      format: \"png\",\n      page: 1\n    }\n  ],\n  store: false\n)\n```\n\nThis method accepts options to set properties of an output file:\n\n- **uuid** — the file UUID-identifier.\n- **format** - defines the target format you want a source file converted to. The supported values are: `pdf` (default), `doc`, `docx`, `xls`, `xlsx`, `odt`, `ods`, `rtf`, `txt`, `jpg`, `png`. In case the format operation was not found, your input document will be converted to `pdf`.\n- **page** - a page number of a multi-paged document to either `jpg` or `png`. The method will not work for any other target formats.\n\n```ruby\n# Response\n{\n  :result =\u003e [\n    {\n      :original_source=\u003e\"a4b9db2f-1591-4f4c-8f68-94018924525d/document/-/format/png/-/page/1/\",\n      :token=\u003e21120220\n      :uuid=\u003e\"88fe5ada-90f1-422a-a233-3a0f3a7cf23c\"\n    }\n  ],\n  :problems=\u003e{}\n}\n```\nParams in the response:\n- **result** - info related to your transformed output(-s):\n  - **original_source** - source file identifier including a target format, if present.\n  - **token** - a processing job token that can be used to get a [job status](https://uploadcare.com/docs/transformations/document-conversion/#status) (see below).\n  - **uuid** - UUID of your processed document file.\n- **problems** - problems related to your processing job, if any.\n\nTo convert multiple documents just add params as a hash for each document to the first argument of the `Uploadcare::DocumentConverter#convert` method:\n\n```ruby\nUploadcare::DocumentConverter.convert(\n  [\n    { doc_one_params }, { doc_two_params }, ...\n  ],\n  store: false\n)\n```\n\nTo check a status of a document processing job you can simply use appropriate method of `Uploadcare::DocumentConverter`:\n\n```ruby\ntoken = 21120220\nUploadcare::DocumentConverter.status(token)\n```\n`token` here is a processing job token, obtained in a response of a convert document request.\n\n```ruby\n# Response\n{\n  :status =\u003e \"finished\",\n  :error =\u003e nil,\n  :result =\u003e {\n    :uuid =\u003e \"a4b9db2f-1591-4f4c-8f68-94018924525d\"\n  }\n}\n```\n\nParams in the response:\n- **status** - processing job status, can have one of the following values:\n  - *pending* — document file is being prepared for conversion.\n  - *processing* — document file processing is in progress.\n  - *finished* — the processing is finished.\n  - *failed* — we failed to process the document, see error for details.\n  - *canceled* — document processing was canceled.\n- **error** - holds a processing error if we failed to handle your document.\n- **result** - repeats the contents of your processing output.\n- **uuid** - a UUID of your processed document file.\n\nMore examples and options can be found [here](https://uploadcare.com/docs/transformations/document-conversion/#document-conversion)\n\n## Secure delivery\n\nYou can use custom domain and CDN provider to deliver files with authenticated URLs (see [original documentation](https://uploadcare.com/docs/security/secure_delivery/)).\n\nTo generate authenticated URL from the library, you should choose `Uploadcare::SignedUrlGenerators::AkamaiGenerator` (or create your own generator implementation):\n\n```ruby\ngenerator = Uploadcare::SignedUrlGenerators::AkamaiGenerator.new(cdn_host: 'example.com', secret_key: 'secret_key')\n# Optional parameters: ttl: 300, algorithm: 'sha256'\ngenerator.generate_url(uuid, acl = optional)\n\ngenerator.generate_url(\"a7d5645e-5cd7-4046-819f-a6a2933bafe3\")\n# https://example.com/a7d5645e-5cd7-4046-819f-a6a2933bafe3/?token=exp=1649405263~acl=/a7d5645e-5cd7-4046-819f-a6a2933bafe3/~hmac=a989cae5342f17013677f5a0e6577fc5594cc4e238fb4c95eda36634eb47018b\n\n# You can pass in ACL as a second parameter to generate_url. See https://uploadcare.com/docs/security/secure-delivery/#authenticated-urls for supported acl formats\ngenerator.generate_url(\"a7d5645e-5cd7-4046-819f-a6a2933bafe3\", '/*/')\n# https://example.com/a7d5645e-5cd7-4046-819f-a6a2933bafe3/?token=exp=1649405263~acl=/*/~hmac=3ce1152c6af8864b36d4dc721f08ca3cf0b3a20278d7f849e82c6c930d48ccc1\n\n# Optionally you can use wildcard: true to generate a wildcard acl token\ngenerator.generate_url(\"a7d5645e-5cd7-4046-819f-a6a2933bafe3\", wildcard: true)\n# https://example.com/a7d5645e-5cd7-4046-819f-a6a2933bafe3/?token=exp=1714233449~acl=/a7d5645e-5cd7-4046-819f-a6a2933bafe3/*~hmac=a568ee2a85dd90a8a8a1ef35ea0cc0ef0acb84fe81990edd3a06eacf10a52b4e\n\n# You can also pass in a custom ttl and algorithm to AkamaiGenerator\ngenerator = Uploadcare::SignedUrlGenerators::AkamaiGenerator.new(cdn_host: 'example.com', secret_key: 'secret_key', ttl: 10)\ngenerator.generate_url(\"a7d5645e-5cd7-4046-819f-a6a2933bafe3\")\n# This generates a URL that expires in 10 seconds\n# https://example.com/a7d5645e-5cd7-4046-819f-a6a2933bafe3/?token=exp=1714233277~acl=/a7d5645e-5cd7-4046-819f-a6a2933bafe3/~hmac=f25343104aeced3004d2cc4d49807d8d7c732300b54b154c319da5283a871a71\n```\n## Useful links\n\n* [Development](https://github.com/uploadcare/uploadcare-ruby/blob/main/DEVELOPMENT.md)\n* [Uploadcare documentation](https://uploadcare.com/docs/?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=uploadcare-ruby)\n* [Upload API reference](https://uploadcare.com/api-refs/upload-api/?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=uploadcare-ruby)\n* [REST API reference](https://uploadcare.com/api-refs/rest-api/?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=uploadcare-ruby)\n* [Changelog](./CHANGELOG.md)\n* [Contributing guide](https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md)\n* [Security policy](https://github.com/uploadcare/uploadcare-ruby/security/policy)\n* [Support](https://github.com/uploadcare/.github/blob/master/SUPPORT.md)\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuploadcare%2Fuploadcare-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuploadcare%2Fuploadcare-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuploadcare%2Fuploadcare-ruby/lists"}