> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a Forma AI image transform

> Generative image operations powered by Forma AI: edit, generate, upscale, background-replace, style-transfer, and outpaint. Returns the produced image as a saved file record. Available on all plans with plan-based Forma AI unit quotas.



## OpenAPI

````yaml /openapi.json post /api/ai/transform
openapi: 3.1.0
info:
  title: Convertly API
  version: 1.0.0
  description: >-
    Convertly provides production API endpoints for media conversion,
    compression, Image CDN delivery, Forma AI, HLS/DASH video streaming, media
    tools, async jobs, workflows, webhooks, and Convertly Storage.
  license:
    name: Proprietary
    url: https://convertly.sh/terms
servers:
  - url: https://convertly.sh
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /api/ai/transform:
    post:
      tags:
        - Forma AI
      summary: Run a Forma AI image transform
      description: >-
        Generative image operations powered by Forma AI: edit, generate,
        upscale, background-replace, style-transfer, and outpaint. Returns the
        produced image as a saved file record. Available on all plans with
        plan-based Forma AI unit quotas.
      operationId: runAiTransform
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - operation
              properties:
                operation:
                  type: string
                  enum:
                    - image.edit
                    - image.generate
                    - image.upscale
                    - image.background-replace
                    - image.style-transfer
                    - image.outpaint
                  description: >-
                    Transform operation to apply. `image.generate` does not
                    require a source image; all others do.
                prompt:
                  type: string
                  maxLength: 2000
                  description: >-
                    Instruction for the transform. Required for editing
                    operations.
                file:
                  type: string
                  format: binary
                  description: >-
                    Image upload. Used when the source is not yet in your
                    library.
                storedFileId:
                  type: string
                  format: uuid
                  description: Reference an existing file in your library as the source.
                sourceUrl:
                  type: string
                  format: uri
                  description: >-
                    Public HTTPS image URL. Private networks and credentialed
                    URLs are rejected.
                aspectRatio:
                  type: string
                  enum:
                    - '1:1'
                    - '16:9'
                    - '9:16'
                    - '4:3'
                    - '3:4'
                    - '3:2'
                    - '2:3'
                    - '21:9'
                  description: >-
                    Output aspect ratio. Most useful for image.generate, which
                    has no source to inherit dimensions from.
                async:
                  type: boolean
                  default: false
                  description: >-
                    When true, the job is enqueued and the response returns a
                    job id immediately. Poll `GET
                    /api/ai/transform/jobs/{jobId}` for the result.
      responses:
        '200':
          description: >-
            Synchronous transform — returns the produced file row and a signed
            download URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  file:
                    type: object
                  result:
                    type: object
                    properties:
                      operation:
                        type: string
                      storedFileId:
                        type: string
                        format: uuid
                      filename:
                        type: string
                      mimeType:
                        type: string
                      size:
                        type: integer
                      downloadUrl:
                        type:
                          - string
                          - 'null'
                      prompt:
                        type: string
                  usage:
                    type: object
                    properties:
                      units:
                        type: integer
                      operation:
                        type: string
        '202':
          description: >-
            Asynchronous mode — job enqueued, poll the jobs endpoint for the
            result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  job:
                    type: object
                    properties:
                      id:
                        type: string
                      status:
                        type: string
                        enum:
                          - queued
                  usage:
                    type: object
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '502':
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        upgradeUrl:
          type: string
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Dashboard-generated Convertly API key. Keys currently begin with
        `cvly_`.
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative API key header for server-side clients.

````