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.