Storyblok Image Transformation API

openapi: 3.1.0
info:
  title: Storyblok Content Delivery API v2 Assets Image Transformation API
  description: The Storyblok Content Delivery API v2 is a REST API that enables developers to fetch published content from a Storyblok space for delivery to end users across web, mobile, and other channels. It provides access to stories, datasources, links, tags, and asset metadata through predictable endpoints with token-based authentication. The API supports filtering, pagination, full-text search, and relation resolution, allowing developers to retrieve precisely the content their application needs. It is optimized for performance and available across multiple regional endpoints to minimize latency for global deployments.
  version: '2'
  contact:
    name: Storyblok Support
    url: https://www.storyblok.com/contact
  termsOfService: https://www.storyblok.com/legal/terms-of-service
servers:
- url: https://api.storyblok.com/v2/cdn
  description: Global Production Server
- url: https://api-us.storyblok.com/v2/cdn
  description: US Production Server
- url: https://api-ap.storyblok.com/v2/cdn
  description: Asia-Pacific Production Server
- url: https://api-ca.storyblok.com/v2/cdn
  description: Canada Production Server
- url: https://api-cn.storyblok.com/v2/cdn
  description: China Production Server
security:
- apiToken: []
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
  securitySchemes:
    apiToken:
      type: apiKey
      in: query
      name: token
      description: Public API token for accessing published content, or Preview API token for accessing draft and published content. Tokens are scoped to a specific Storyblok space.
externalDocs:
  description: Storyblok Content Delivery API v2 Documentation
  url: https://www.storyblok.com/docs/api/content-delivery/v2