openapi: 3.0.1
info:
title: Cloudimage API
description: >-
Cloudimage (by Scaleflex) is a URL-based image and video transformation,
optimization, and CDN service. Image and video operations are expressed
entirely as query parameters on a GET request to the
https://{token}.cloudimg.io host, where the origin media URL is carried as
the request path. Operations include resizing, cropping, format conversion,
compression, filters, and watermarks. A companion Filerobot DAM REST API
(https://api.filerobot.com/{token}/v4) provides upload and asset management.
This document models the documented public surface; it does not enumerate
every one of the 50+ transformation parameters.
termsOfService: https://www.cloudimage.io/en/terms-and-conditions
contact:
name: Cloudimage / Scaleflex Support
url: https://www.cloudimage.io/
version: '7'
servers:
- url: https://{token}.cloudimg.io
description: Cloudimage URL-based transformation and CDN host. {token} is the account identifier.
variables:
token:
default: demo
description: Your Cloudimage account token (subdomain).
- url: https://api.filerobot.com/{token}/v4
description: Filerobot DAM upload and asset-management REST API.
variables:
token:
default: demo
description: Your Filerobot/Cloudimage account token.
tags:
- name: Image
description: URL-based image transformation operations.
- name: Video
description: URL-based video transformation and transcoding operations.
- name: Filerobot DAM
description: Upload and asset-management REST endpoints.
paths:
/{origin}:
get:
operationId: transformImage
tags:
- Image
summary: Transform and deliver an image
description: >-
Requests the origin image and applies transformation operations supplied
as query parameters. The origin image URL is carried as the request path
(e.g. https://{token}.cloudimg.io/https://samples.scaleflex.com/flat.jpg).
When the origin contains a query string or reserved characters,
percent-encode it and add ci_url_encoded=1.
parameters:
- name: origin
in: path
required: true
description: The origin (source) image URL appended as the request path.
schema:
type: string
example: https://samples.scaleflex.com/flat.jpg
- name: w
in: query
description: Target width in pixels (alias of width).
schema:
type: integer
example: 400
- name: h
in: query
description: Target height in pixels (alias of height).
schema:
type: integer
example: 300
- name: func
in: query
description: >-
Resize function applied when both width and height are provided.
crop is the default.
schema:
type: string
enum: [crop, fit, cropfit, bound, boundmin, cover]
default: crop
- name: gravity
in: query
description: >-
Focal point used when cropping. Accepts compass values
([north|south][east|west]), center, auto, smart, face, or X,Y coordinates.
schema:
type: string
example: smart
- name: org_if_sml
in: query
description: When set to 1, prevents upscaling beyond the original dimensions.
schema:
type: integer
enum: [0, 1]
- name: tl_px
in: query
description: Top-left corner X,Y coordinates for a positionable crop.
schema:
type: string
example: 100,50
- name: br_px
in: query
description: Bottom-right corner X,Y coordinates for a positionable crop.
schema:
type: string
example: 400,300
- name: flip
in: query
description: Mirror the image horizontally (h), vertically (v), or both (hv).
schema:
type: string
enum: [h, v, hv]
- name: r
in: query
description: Rotate the image counterclockwise by the given number of degrees.
schema:
type: integer
- name: trim
in: query
description: Remove solid-color borders; value sets aggressiveness.
schema:
type: integer
- name: radius
in: query
description: Round image corners by the given radius (optionally with a fill color).
schema:
type: string
- name: force_format
in: query
description: Force the output format (alias of format / f).
schema:
type: string
enum: [auto, webp, avif, jpeg, png, gif]
default: auto
- name: q
in: query
description: Output compression quality (1-100).
schema:
type: integer
minimum: 1
maximum: 100
default: 80
- name: blur
in: query
description: Apply a Gaussian blur of the given strength.
schema:
type: integer
- name: sharpen
in: query
description: Apply sharpening of the given strength.
schema:
type: integer
- name: contrast
in: query
description: Adjust image contrast.
schema:
type: integer
- name: saturate
in: query
description: Adjust image saturation.
schema:
type: integer
- name: greyscale
in: query
description: Convert the image to greyscale when set to 1.
schema:
type: integer
enum: [0, 1]
- name: pixellate
in: query
description: Apply a pixelation effect of the given strength.
schema:
type: integer
- name: bg_remove
in: query
description: Remove the background using AI when set to 1 (consumes a visual operation).
schema:
type: integer
enum: [0, 1]
- name: wat
in: query
description: Enable a watermark overlay when set to 1.
schema:
type: integer
enum: [0, 1]
- name: wat_url
in: query
description: URL of the image to use as a watermark (defines a dynamic watermark).
schema:
type: string
- name: wat_text
in: query
description: Text content for a text watermark.
schema:
type: string
- name: wat_gravity
in: query
description: Watermark position (e.g. northeast, center).
schema:
type: string
- name: wat_scale
in: query
description: Watermark scale relative to the image.
schema:
type: string
- name: wat_pad
in: query
description: Watermark padding from the edge.
schema:
type: string
- name: wat_opacity
in: query
description: Watermark opacity (0-100).
schema:
type: integer
- name: ci_url_encoded
in: query
description: Set to 1 when the origin URL is percent-encoded in the path.
schema:
type: integer
enum: [0, 1]
responses:
'200':
description: The transformed image binary, delivered via CDN.
content:
image/webp:
schema:
type: string
format: binary
image/avif:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
'404':
description: Origin image not found or unreachable.
/{origin}.mp4:
get:
operationId: transformVideo
tags:
- Video
summary: Transform and deliver a video
description: >-
On-the-fly video processing and transcoding using the same URL model as
images. Input is limited to 500 MB, up to 4K, and the first 60 seconds.
parameters:
- name: origin
in: path
required: true
description: The origin (source) video URL appended as the request path.
schema:
type: string
example: https://samples.scaleflex.com/sample.mp4
- name: w
in: query
description: Target video width in pixels (greater than 100).
schema:
type: integer
- name: h
in: query
description: Target video height in pixels (greater than 100).
schema:
type: integer
- name: func
in: query
description: Resize function applied when both width and height are provided.
schema:
type: string
enum: [crop, fit, cropfit, bound, boundmin, cover]
- name: bg_color
in: query
description: Background (padding) color used with func=fit (hex code or color name).
schema:
type: string
- name: bg_img_fit
in: query
description: Use a blurred version of the video for the background/padding when set to 1.
schema:
type: integer
enum: [0, 1]
- name: format
in: query
description: Output video format.
schema:
type: string
enum: [auto, mp4, webm, h264.mp4, h265.mp4, vp9.webm]
default: auto
- name: bitrate
in: query
description: Compression bitrate (10k-20000k or 1m-20m).
schema:
type: string
responses:
'200':
description: The transcoded video binary, delivered via CDN.
content:
video/mp4:
schema:
type: string
format: binary
video/webm:
schema:
type: string
format: binary
/upload:
post:
operationId: uploadFile
tags:
- Filerobot DAM
summary: Upload a file to the DAM
description: >-
Uploads one or more files into the Filerobot DAM via multipart/form-data.
Served from the Filerobot host https://api.filerobot.com/{token}/v4.
servers:
- url: https://api.filerobot.com/{token}/v4
variables:
token:
default: demo
parameters:
- name: folder
in: query
description: Destination folder path within the DAM.
schema:
type: string
example: /folder_test
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
responses:
'200':
description: File uploaded; metadata for the stored asset is returned.
security:
- filerobotKey: []
/files:
get:
operationId: listFiles
tags:
- Filerobot DAM
summary: List and search files
description: Lists or searches files stored in the DAM.
servers:
- url: https://api.filerobot.com/{token}/v4
variables:
token:
default: demo
responses:
'200':
description: A list of files matching the query.
security:
- filerobotKey: []
put:
operationId: streamUploadFile
tags:
- Filerobot DAM
summary: Stream-upload a file
description: >-
Streams the request body into the storage container; useful for files
larger than 500 MB. Sends application/octet-stream.
servers:
- url: https://api.filerobot.com/{token}/v4
variables:
token:
default: demo
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: File stored; asset metadata returned.
security:
- filerobotKey: []
/files/{uuid}:
get:
operationId: getFile
tags:
- Filerobot DAM
summary: Get file details
servers:
- url: https://api.filerobot.com/{token}/v4
variables:
token:
default: demo
parameters:
- name: uuid
in: path
required: true
schema:
type: string
responses:
'200':
description: File metadata.
security:
- filerobotKey: []
delete:
operationId: deleteFile
tags:
- Filerobot DAM
summary: Delete a file
servers:
- url: https://api.filerobot.com/{token}/v4
variables:
token:
default: demo
parameters:
- name: uuid
in: path
required: true
schema:
type: string
responses:
'200':
description: File deleted.
security:
- filerobotKey: []
/folders:
get:
operationId: listFolders
tags:
- Filerobot DAM
summary: List and search folders
servers:
- url: https://api.filerobot.com/{token}/v4
variables:
token:
default: demo
responses:
'200':
description: A list of folders.
security:
- filerobotKey: []
post:
operationId: createFolder
tags:
- Filerobot DAM
summary: Create a folder
servers:
- url: https://api.filerobot.com/{token}/v4
variables:
token:
default: demo
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
parent:
type: string
responses:
'200':
description: Folder created.
security:
- filerobotKey: []
components:
securitySchemes:
filerobotKey:
type: apiKey
in: header
name: X-Filerobot-Key
description: Filerobot DAM API key.