Storyblok Image Transformation API

openapi: 3.2.0
info:
  title: Storyblok Image Service Image Transformation API
  description: The Storyblok Image Service is a URL-based image transformation API that allows developers to resize, crop, convert, and optimize images hosted in Storyblok's asset CDN. Transformations are applied by constructing a specific URL with path segments and filter parameters that specify dimensions, format conversion, quality, focal point, and filter effects. The service eliminates the need for a separate image processing pipeline and is suitable for responsive images, thumbnails, and format-optimized delivery across web and mobile applications. Images are served via a global CDN for fast delivery.
  version: '2'
  contact:
    name: Storyblok Support
    url: https://www.storyblok.com/contact
  termsOfService: https://www.storyblok.com/legal/terms-of-service
servers:
- url: https://img2.storyblok.com
  description: Storyblok Image CDN
tags:
- name: Image Transformation
  description: URL-based image transformation operations applied by constructing a specific path structure following the base asset URL. All operations require the /m/ path segment prefix.
paths:
  /{asset_path}/m/:
    get:
      operationId: getOriginalImage
      summary: Retrieve original image with transformation routing enabled
      description: Returns the original image without any transformation. The /m/ path segment activates the Image Service transformation routing for all subsequent operations. Any further path segments after /m/ apply transformations such as resizing, cropping, and filter effects.
      tags:
      - Image Transformation
      parameters:
      - $ref: '#/components/parameters/AssetPath'
      responses:
        '200':
          description: The image was returned successfully.
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /{asset_path}/m/{width}x{height}:
    get:
      operationId: resizeImage
      summary: Resize an image to specified dimensions
      description: Returns the image resized to the specified width and height in pixels. If only width is provided (e.g., 500x0), the height is scaled proportionally. If only height is provided (e.g., 0x300), the width is scaled proportionally. Both dimensions set to 0 returns the original size.
      tags:
      - Image Transformation
      parameters:
      - $ref: '#/components/parameters/AssetPath'
      - name: width
        in: path
        description: Target width in pixels. Set to 0 to scale proportionally based on height.
        required: true
        schema:
          type: integer
          minimum: 0
        example: 500
      - name: height
        in: path
        description: Target height in pixels. Set to 0 to scale proportionally based on width.
        required: true
        schema:
          type: integer
          minimum: 0
        example: 300
      responses:
        '200':
          description: The resized image was returned successfully.
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /{asset_path}/m/{width}x{height}/filters:{filter_chain}:
    get:
      operationId: transformImageWithFilters
      summary: Transform image with resize and filter chain
      description: Returns the image after applying a resize operation and one or more filters. Filters are chained using colons in the filter_chain path segment. Supported filter functions include format(webp|jpeg|png|avif), quality(0-100), fill(color_hex), blur(amount), grayscale(), focal(x:y), rotate(degrees), brightness(amount), and crop(top_left_x, top_left_y, bottom_right_x, bottom_right_y). Multiple filters are separated by colons, for example filters:format(webp):quality(80).
      tags:
      - Image Transformation
      parameters:
      - $ref: '#/components/parameters/AssetPath'
      - name: width
        in: path
        description: Target width in pixels. Set to 0 for proportional scaling.
        required: true
        schema:
          type: integer
          minimum: 0
        example: 800
      - name: height
        in: path
        description: Target height in pixels. Set to 0 for proportional scaling.
        required: true
        schema:
          type: integer
          minimum: 0
        example: 600
      - name: filter_chain
        in: path
        description: 'Colon-separated chain of filter function calls to apply to the image. Each filter is specified as name(value). For example: format(webp):quality(80):fill(transparent).'
        required: true
        schema:
          type: string
        example: format(webp):quality(80)
      responses:
        '200':
          description: The transformed image was returned successfully.
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /{asset_path}/m/fit-in/{width}x{height}:
    get:
      operationId: fitInImage
      summary: Fit image within specified dimensions without cropping
      description: Returns the image scaled to fit within the specified width and height while maintaining aspect ratio and without cropping. The resulting image will not exceed the specified dimensions but may be smaller if the aspect ratios differ. Combine with a fill filter to pad the background color.
      tags:
      - Image Transformation
      parameters:
      - $ref: '#/components/parameters/AssetPath'
      - name: width
        in: path
        description: Maximum width in pixels for the fit-in operation.
        required: true
        schema:
          type: integer
          minimum: 1
        example: 400
      - name: height
        in: path
        description: Maximum height in pixels for the fit-in operation.
        required: true
        schema:
          type: integer
          minimum: 1
        example: 400
      responses:
        '200':
          description: The fit-in image was returned successfully.
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested asset was not found at the given path.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message describing why the asset was not found.
  parameters:
    AssetPath:
      name: asset_path
      in: path
      description: The path portion of the original Storyblok asset CDN URL after the hostname. For example, if the asset URL is https://img2.storyblok.com/f/12345/1200x800/photo.jpg, the asset_path is f/12345/1200x800/photo.jpg.
      required: true
      schema:
        type: string
      example: f/12345/1200x800/photo.jpg
externalDocs:
  description: Storyblok Image Service Documentation
  url: https://www.storyblok.com/docs/api/image-service