Skip to main content
POST
/
api
/
files
/
{id}
/
tools
Run a media tool against a stored file
curl --request POST \
  --url https://convertly.sh/api/files/{id}/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "file": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "filename": "<string>",
    "mime_type": "<string>",
    "size_bytes": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "downloadUrl": "<string>"
  }
}

Authorizations

Authorization
string
header
required

Dashboard-generated Convertly API key. Keys currently begin with cvly_.

Path Parameters

id
string<uuid>
required

Body

application/json
tool
enum<string>
required

Which Media Tools operation to run against the stored file.

Available options:
remove-background,
transform,
vectorize,
watermark,
adjust,
trim,
convert,
extract-audio,
gif,
poster-frame,
storyboard
params
object

Tool-specific parameters. Send the same fields you would send as form data to the equivalent /api/media/* route, as a JSON object of string values.

preview
boolean
default:false

When true, returns a base64 data URL in the response without writing a new stored file. Useful for in-app previews.

watermarkLogoDataUrl
string

Watermark only. A data: URL containing the logo image. Required for tool=watermark with a logo input.

Response

New stored file (or preview when preview=true)

file
object
required