Freepik Image Expand API

openapi: 3.2.0
info:
  description: The Magnific API is your gateway to a vast collection of high-quality digital resources for your applications and projects. As a leading platform, it offers a wide range of graphics, including vectors, photos, illustrations, icons, PSD templates, and more, all curated by talented designers from around the world.
  title: Magnific Image Expand API
  version: 1.0.0
servers:
- description: B2B API Production V1
  url: https://api.magnific.com
security:
- magnificApiKey: []
tags:
- name: image-expand
paths:
  /v1/ai/image-expand/flux-pro:
    get:
      responses:
        '200':
          $ref: '#/components/responses/task-list-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Get the status of all image expand tasks
      tags:
      - image-expand
      operationId: getV1AiImageExpandFluxPro
      x-operation-id-source: derived
    post:
      description: 'This endpoint allows you to expand an image using the AI Flux Pro model. The image will be expanded based on the provided parameters.


        ### Input size


        The image you send must be **at least 256 pixels on each side** and **no

        larger than 20 megapixels** (`width * height <= 20,000,000`). Neither side

        is capped on its own and there is no aspect ratio restriction: a 30000x600

        image is accepted, while a 255x70500 one is rejected because one of its

        sides is below 256, even though it is only 18 megapixels.


        File size is irrelevant — what counts is the decoded pixel count, so a

        heavily compressed 60 megapixel photo is rejected just the same. An image

        outside these bounds is rejected with an error naming the rule it broke.


        Sending more than 20 megapixels buys you nothing anyway: the output is

        capped at roughly 1.6 megapixels regardless of how large the input was, so

        resize before uploading.


        ### Output size


        `left`, `right`, `top` and `bottom` describe the expansion you are asking for,

        but **this model does not guarantee that exact output size**. The requested

        canvas is `input_width + left + right` by `input_height + top + bottom`, and

        two rules are then applied to it:


        1. **Maximum output size of roughly 1.6 megapixels.** If the requested canvas

        is larger, the whole image is scaled down proportionally until it fits. The

        aspect ratio is preserved, so there is no single maximum width or height:

        the cap applies to the total pixel count. A 1200x400 image expanded by 400

        pixels on each edge asks for a 2000x1200 canvas and comes back as 1632x976.

        2. **Each side is rounded to the nearest multiple of 16.** A requested

        916x692 comes back as 912x688; a requested 936x712 comes back as 944x720.


        Both rules apply on every request, including small ones, so an output that

        matches your requested pixels exactly is the exception rather than the rule.


        Omitting an edge applies its default (512 left, 512 right, 256 top, 256

        bottom). Sending `0` leaves that edge unexpanded; sending `0` on all four

        edges returns a `400`, since there is nothing to expand.


        That said, **this is the expand endpoint that stays closest to the pixel

        values you request**: below the 1.6 megapixel cap, the rounding to 16 is the

        only deviation. Expanding an 896x672 image by 500 pixels on the top edge

        alone asks for 896x1172 and returns 896x1168. The other two expand endpoints

        diverge much further:

        `ideogram` always renders at about 1 megapixel and only preserves the aspect

        ratio, and `seedream-v4-5` scales any canvas below 3.7 megapixels up. If you

        need exact output dimensions, resize the result yourself after generation.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/image-expand-request'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/task-detail-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Flux Pro - Expand image
      tags:
      - image-expand
      operationId: postV1AiImageExpandFluxPro
      x-operation-id-source: derived
  /v1/ai/image-expand/flux-pro/{task-id}:
    get:
      parameters:
      - description: ID of the task
        in: path
        name: task-id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/task-detail-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Get the status of one image expand task
      tags:
      - image-expand
      operationId: getV1AiImageExpandFluxProByTaskId
      x-operation-id-source: derived
  /v1/ai/image-expand/ideogram:
    get:
      responses:
        '200':
          $ref: '#/components/responses/task-list-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Get the status of all image expand ideogram tasks
      tags:
      - image-expand
      operationId: getV1AiImageExpandIdeogram
      x-operation-id-source: derived
    post:
      description: 'This endpoint allows you to expand an image using the Ideogram AI model. The image will be expanded based on the provided pixel values for each side.

        If no prompt is provided, the model will auto-generate one based on the image content.


        ### Output size


        `left`, `right`, `top` and `bottom` define the **aspect ratio** of the result,

        not its pixel dimensions. The canvas is built as

        `input_width + left + right` by `input_height + top + bottom`, and the model

        then renders it at **approximately 1 megapixel**, picking the closest match

        from its own fixed list of supported resolutions (all multiples of 32). The

        pixel values you send are therefore not preserved:


        | Requested canvas | Actual output |

        | --- | --- |

        | 896x1172 | 832x1088 |

        | 1396x672 | 1472x704 |

        | 896x896 | 1024x1024 |

        | 4992x4768 | 1024x960 |


        As the last row shows, a very large expansion does not produce a larger image:

        it only changes the shape. If you need specific output dimensions, resize the

        result yourself after generation.


        `left`, `right`, `top` and `bottom` are all required. At least one of them

        must be greater than `0`, otherwise the request returns a `400`; the other

        three may be `0`.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/image-expand-ideogram-request'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/task-detail-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Ideogram - Expand image
      tags:
      - image-expand
      operationId: postV1AiImageExpandIdeogram
      x-operation-id-source: derived
  /v1/ai/image-expand/ideogram/{task-id}:
    get:
      parameters:
      - description: ID of the task
        in: path
        name: task-id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/task-detail-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Get the status of one image expand ideogram task
      tags:
      - image-expand
      operationId: getV1AiImageExpandIdeogramByTaskId
      x-operation-id-source: derived
  /v1/ai/image-expand/seedream-v4-5:
    get:
      responses:
        '200':
          $ref: '#/components/responses/task-list-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Get the status of all image expand seedream v4.5 tasks
      tags:
      - image-expand
      operationId: getV1AiImageExpandSeedreamV45
      x-operation-id-source: derived
    post:
      description: 'This endpoint allows you to expand an image using the Seedream V4.5 AI model. The image will be expanded based on the provided pixel values for each side.

        If no prompt is provided, the model will auto-generate one based on the image content.


        ### Output size


        The requested canvas is `input_width + left + right` by

        `input_height + top + bottom`, and this model constrains it in two ways:


        1. **Each side is rounded up to the next multiple of 16.**

        2. **The canvas must contain between 3,686,400 and 16,777,216 pixels.** A

        smaller canvas is scaled **up** to reach the lower bound, and a larger one

        is scaled down to the upper bound. Since the lower bound is close to 3.7

        megapixels, a small input with a small expansion is upscaled — a 896x672

        image expanded by 100px on each edge asks for a 1096x872 canvas and comes

        back at 2160x1728, close to twice the requested dimensions (measured).


        If you need the output to stay close to the pixel values you requested, use

        `POST /v1/ai/image-expand/flux-pro`, which only deviates by the rounding to 16

        while the result stays under 1.6 megapixels. For exact dimensions, resize the

        result yourself after generation.


        `left`, `right`, `top` and `bottom` are all required, and at least one of them

        must be greater than `0`.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/image-expand-seedream-v4-5-request'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/task-detail-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Seedream V4.5 - Expand image
      tags:
      - image-expand
      operationId: postV1AiImageExpandSeedreamV45
      x-operation-id-source: derived
  /v1/ai/image-expand/seedream-v4-5/{task-id}:
    get:
      parameters:
      - description: ID of the task
        in: path
        name: task-id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/task-detail-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Get the status of one image expand seedream v4.5 task
      tags:
      - image-expand
      operationId: getV1AiImageExpandSeedreamV45ByTaskId
      x-operation-id-source: derived
components:
  schemas:
    inline_object_4:
      example:
        data:
          generated:
          - https://openapi-generator.tech
          - https://openapi-generator.tech
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
      properties:
        data:
          $ref: '#/components/schemas/task-detail_1'
      required:
      - data
      type: object
    image-expand-ideogram-request:
      properties:
        webhook_url:
          description: 'Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field.

            '
          example: https://www.example.com/webhook
          format: uri
          type: string
        image:
          description: Base64 image to expand
          format: byte
          type: string
        prompt:
          description: Optional text prompt describing the desired expanded content. If not provided, the AI model will auto-generate a prompt based on the image.
          type: string
        left:
          description: Number of pixels to expand on the left side
          maximum: 2048
          minimum: 0
          type: integer
        right:
          description: Number of pixels to expand on the right side
          maximum: 2048
          minimum: 0
          type: integer
        top:
          description: Number of pixels to expand on the top side
          maximum: 2048
          minimum: 0
          type: integer
        bottom:
          description: Number of pixels to expand on the bottom side
          maximum: 2048
          minimum: 0
          type: integer
        seed:
          description: Optional seed for reproducibility
          maximum: 2147483647
          minimum: 0
          type: integer
      required:
      - bottom
      - image
      - left
      - right
      - top
      type: object
    inline_object_1_problem_invalid_params_inner:
      properties:
        name:
          description: Name of the invalid parameter.
          example: page
          type: string
        field:
          description: Field of the invalid parameter. Mirrors `name`.
          example: page
          type: string
        reason:
          example: Parameter 'page' must be greater than 0
          type: string
      required:
      - field
      - name
      - reason
      type: object
    task:
      example:
        task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: CREATED
      properties:
        task_id:
          description: Task identifier
          format: uuid
          type: string
        status:
          description: Task status
          enum:
          - CREATED
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          type: string
      required:
      - status
      - task_id
      type: object
    inline_object_1:
      properties:
        problem:
          $ref: '#/components/schemas/inline_object_1_problem'
      type: object
    inline_object_1_problem:
      properties:
        message:
          example: Validation error
          type: string
        invalid_params:
          items:
            $ref: '#/components/schemas/inline_object_1_problem_invalid_params_inner'
          type: array
      required:
      - invalid_params
      - message
      type: object
    inline_object_2:
      example:
        message: Internal Server Error
      properties:
        message:
          example: Internal Server Error
          type: string
      type: object
    inline_object:
      example:
        message: message
      properties:
        message:
          type: string
      type: object
    image-expand-request:
      properties:
        webhook_url:
          description: 'Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field.

            '
          example: https://www.example.com/webhook
          format: uri
          type: string
        image:
          description: Base64 image to expand
          format: byte
          type: string
        prompt:
          description: The description of the changes you want to make. This text guides the expansion process, allowing you to specify features, styles, or modifications for the expanded areas.
          type: string
        left:
          default: 512
          description: 'Pixels to expand on the left. Omit the field to use the default of `512`;

            send `0` to leave this edge unexpanded. The requested size is not always

            the size you get back — see the description of this endpoint.

            '
          maximum: 2048
          minimum: 0
          type:
          - integer
          - 'null'
        right:
          default: 512
          description: 'Pixels to expand on the right. Omit the field to use the default of `512`;

            send `0` to leave this edge unexpanded.

            '
          maximum: 2048
          minimum: 0
          type:
          - integer
          - 'null'
        top:
          default: 256
          description: 'Pixels to expand on the top. Omit the field to use the default of `256`;

            send `0` to leave this edge unexpanded.

            '
          maximum: 2048
          minimum: 0
          type:
          - integer
          - 'null'
        bottom:
          default: 256
          description: 'Pixels to expand on the bottom. Omit the field to use the default of `256`;

            send `0` to leave this edge unexpanded.

            '
          maximum: 2048
          minimum: 0
          type:
          - integer
          - 'null'
      required:
      - image
      type: object
    inline_object_3:
      example:
        message: Service Unavailable. Please try again later.
      properties:
        message:
          example: Service Unavailable. Please try again later.
          type: string
      type: object
    image-expand-seedream-v4-5-request:
      properties:
        webhook_url:
          description: 'Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field.

            '
          example: https://www.example.com/webhook
          format: uri
          type: string
        image:
          description: Image to expand. Accepts an HTTPS URL or a Base64-encoded image (max 10MB).
          type: string
        prompt:
          description: Optional text prompt describing the desired expanded content. If not provided, the AI model will auto-generate a prompt based on the image.
          type: string
        left:
          description: Number of pixels to expand on the left side
          maximum: 2048
          minimum: 0
          type: integer
        right:
          description: Number of pixels to expand on the right side
          maximum: 2048
          minimum: 0
          type: integer
        top:
          description: Number of pixels to expand on the top side
          maximum: 2048
          minimum: 0
          type: integer
        bottom:
          description: Number of pixels to expand on the bottom side
          maximum: 2048
          minimum: 0
          type: integer
        seed:
          description: Optional seed for reproducibility
          maximum: 2147483647
          minimum: 0
          type: integer
      required:
      - bottom
      - image
      - left
      - right
      - top
      type: object
    get_all_style_transfer_tasks_200_response:
      example:
        data:
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
      properties:
        data:
          items:
            $ref: '#/components/schemas/task'
          type: array
      required:
      - data
      type: object
    task-detail_1:
      allOf:
      - $ref: '#/components/schemas/task'
      - properties:
          generated:
            items:
              description: URL of the generated image
              format: uri
              type: string
            type: array
        required:
        - generated
        type: object
      example:
        generated:
        - https://openapi-generator.tech
        - https://openapi-generator.tech
        task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: CREATED
  responses:
    401-unauthorized:
      content:
        application/json:
          examples:
            invalid_api_key:
              summary: API key is not valid
              value:
                message: Invalid API key
            missing_api_key:
              summary: API key is not provided
              value:
                message: Missing API key
          schema:
            $ref: '#/components/schemas/inline_object'
      description: Unauthorized - The client must authenticate itself to get the requested response.
    503-service-unavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_object_3'
      description: Service Unavailable
    task-detail-200-default-response:
      content:
        application/json:
          examples:
            success - created task:
              $ref: '#/components/examples/200-task-created'
            success - in progress task:
              $ref: '#/components/examples/200-task-in-progress'
            success - completed task:
              $ref: '#/components/examples/200-task-completed'
            success - failed task:
              $ref: '#/components/examples/200-task-failed'
          schema:
            $ref: '#/components/schemas/inline_object_4'
      description: OK - The task exists and the status is returned
    400-bad-request:
      content:
        application/json:
          examples:
            invalid_page:
              summary: Parameter 'page' is not valid
              value:
                message: Parameter 'page' must be greater than 0
            invalid_query:
              summary: Parameter 'query' is not valid
              value:
                message: Parameter 'query' must not be empty
            invalid_filter:
              summary: Parameter 'filter' is not valid
              value:
                message: Parameter 'filter' is not valid
            generic_bad_request:
              summary: Bad Request
              value:
                message: Parameter ':attribute' is not valid
          schema:
            $ref: '#/components/schemas/inline_object'
        application/problem+json:
          examples:
            invalid_page:
              summary: Parameter 'page' is not valid
              value:
                message: Validation error
                invalid_params:
                - field: page
                  reason: Parameter 'page' must be greater than 0
                - field: per_page
                  reason: Parameter 'per_page' must be greater than 0
          schema:
            $ref: '#/components/schemas/inline_object_1'
      description: Bad Request - The server could not understand the request due to invalid syntax.
    500-internal-server-error:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_object_2'
      description: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
    task-list-200-default-response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/get_all_style_transfer_tasks_200_response'
      description: OK - Returns a list of tasks for the current type of Task
  examples:
    200-task-failed:
      summary: Success - Task failed
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: FAILED
    200-task-in-progress:
      summary: Success - Task in progress
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
    200-task-created:
      summary: Success - Task created
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
    200-task-completed:
      summary: Success - Task completed
      value:
        data:
          generated:
          - https://ai-statics.freepik.com/completed_task_image.jpg
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: COMPLETED
  securitySchemes:
    magnificApiKey:
      description: 'Your Magnific API key. Required for authentication. [Learn how to obtain an API key](https://docs.magnific.com/quickstart)

        '
      in: header
      name: x-magnific-api-key
      type: apiKey
x-provenance:
  method: harvested
  publisher: Freepik
  source: https://storage.googleapis.com/fc-freepik-pro-rev1-eu-api-specs/magnific-api-v1-openapi.yaml?v=46\
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)