Freepik Image Relight 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 Relight API
  version: 1.0.0
servers:
- description: B2B API Production V1
  url: https://api.magnific.com
security:
- magnificApiKey: []
tags:
- name: image-relight
paths:
  /v1/ai/image-relight:
    get:
      description: Get the status of all relight tasks
      responses:
        '200':
          content:
            application/json:
              examples:
                success - return all tasks:
                  $ref: '#/components/examples/200-tasks-list'
              schema:
                $ref: '#/components/schemas/get_all_style_transfer_tasks_200_response'
          description: OK - Get the status of all relight tasks
        '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: Relight - List tasks
      tags:
      - image-relight
      operationId: getV1AiImageRelight
      x-operation-id-source: derived
    post:
      description: Relight an image using AI. This endpoint accepts a variety of parameters to customize the generated images.
      requestBody:
        content:
          application/json:
            examples:
              all-params:
                $ref: '#/components/examples/request-image-relight-all-params'
              required-params:
                $ref: '#/components/examples/request-image-relight-required-params'
            schema:
              $ref: '#/components/schemas/relight-request'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_style_transfer_task_status_200_response'
          description: OK - The request has succeeded and the relight process has started.
        '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: Relight - Adjust image lighting
      tags:
      - image-relight
      operationId: postV1AiImageRelight
      x-operation-id-source: derived
  /v1/ai/image-relight/{task-id}:
    get:
      description: Get the status of the relight task
      parameters:
      - description: ID of the task
        in: path
        name: task-id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                success - completed task:
                  $ref: '#/components/examples/200-task-completed'
                success - in progress task:
                  $ref: '#/components/examples/200-task-in-progress'
              schema:
                $ref: '#/components/schemas/get_style_transfer_task_status_200_response'
          description: OK - The task exists and the status is returned
        '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: Relight - Get task status
      tags:
      - image-relight
      operationId: getV1AiImageRelightByTaskId
      x-operation-id-source: derived
components:
  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
    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.
  schemas:
    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
    get_style_transfer_task_status_200_response:
      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'
      required:
      - data
      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
    relight-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 or URL of the image to do the relight
          type: string
        prompt:
          description: 'You can guide the generation process and influence the light transfer with a descriptive prompt. For example, if the reference image is a brightly lit scene, adding something like "A sunlit forest clearing at golden hour" will be helpful.


            You can also use your imagination to alter lighting conditions in images: transforming a daytime scene into a moonlit night, enhancing the warmth of a sunset, or even dramatic changes like casting shadows of towering structures across a cityscape.


            IMPORTANT: You can emphasize specific aspects of the light in your prompt by using a number in parentheses, ranging from 1 to 1.4, like "(dark scene:1.3)".

            '
          type: string
        transfer_light_from_reference_image:
          description: Base64 or URL of the reference image for light transfer. Incompatible with 'transfer_light_from_lightmap'
          type: string
        transfer_light_from_lightmap:
          description: Base64 or URL of the lightmap for light transfer. Icompatible with 'transfer_light_from_reference_image'
          type: string
        light_transfer_strength:
          default: 100
          description: 'It allows you to specify the level of light transfer, meaning the intensity that your prompt, reference image, or lightmap will have. A value of 0% will keep your image closest to the original, while 100% represents the maximum possible light transfer.


            If you enable "Interpolate from original", lower values on this slider will make the result even more similar to your original image.

            Valid values range `[0, 100]`, default `100`

            '
          maximum: 100
          minimum: 0
          type: integer
        interpolate_from_original:
          default: false
          description: 'When enabled, this feature will make your final image interpolate from the original using the "Light transfer strength" slider, at the cost of sometimes restricting the generation''s freedom.


            If disabled, the generation will be freer and will generally produce better results. However, for example, if you want to generate all the frames of a video where a room transitions from having the lights off and very dim lighting to gradually becoming fully illuminated as a new day begins, activating this option might be useful (together with gradually ingreasing the "Light transfer strength" slider).

            '
          type: boolean
        change_background:
          default: true
          description: 'When enabled, it will change the background based on your prompt and/or reference image. This is super useful for product placement and portraits. However, don''t forget to disable it if your scene is something like a landscape or an interior.

            '
          type: boolean
        style:
          default: standard
          enum:
          - standard
          - darker_but_realistic
          - clean
          - smooth
          - brighter
          - contrasted_n_hdr
          - just_composition
          type: string
        preserve_details:
          default: true
          description: 'It will try to maintain the texture and small details of the original image. Especially good for product photography, texts, etc. Disable it if you prefer a smoother result.

            '
          type: boolean
        advanced_settings:
          $ref: '#/components/schemas/relight-request-advanced-settings'
      required:
      - image
      type: object
    relight-request-advanced-settings:
      properties:
        whites:
          default: 50
          description: 'Adjust the level of white color in the image.

            Valid values range `[0, 100]`, default `50`.

            '
          maximum: 100
          minimum: 0
          type: integer
        blacks:
          default: 50
          description: 'Adjust the level of black color in the image.

            Valid values range `[0, 100]`, default `50`.

            '
          maximum: 100
          minimum: 0
          type: integer
        brightness:
          default: 50
          description: 'Adjust the level of brightness in the image.

            Valid values range `[0, 100]`, default `50`.

            '
          maximum: 100
          minimum: 0
          type: integer
        contrast:
          default: 50
          description: 'Adjust the level of contrast in the image.

            Valid values range `[0, 100]`, default `50`.

            '
          maximum: 100
          minimum: 0
          type: integer
        saturation:
          default: 50
          description: 'Adjust the level of saturation in the image.

            Valid values range `[0, 100]`, default `50`.

            '
          maximum: 100
          minimum: 0
          type: integer
        engine:
          default: automatic
          description: 'Balanced: Well-rounded, general-purpose option.

            Cool: Brighter with cooler tones.

            Real: Aims to enhance photographic quality. Experimental.

            Illusio: Optimized for illustrations and drawings.

            Fairy: Suited for fantasy-themed images.

            Colorful Anime: Ideal for anime, cartoons, and vibrant colors.

            Hard Transform: Significantly alters the original image.

            Softy: Slightly softer effect, suitable for graphic designs.

            '
          enum:
          - automatic
          - balanced
          - cool
          - real
          - illusio
          - fairy
          - colorful_anime
          - hard_transform
          - softy
          type: string
        transfer_light_a:
          default: automatic
          description: Adjusts the intensity of light transfer. Advanced feature requiring practice to use effectively.
          enum:
          - automatic
          - low
          - medium
          - normal
          - high
          - high_on_faces
          type: string
        transfer_light_b:
          default: automatic
          description: Also modifies light transfer intensity. Can be combined with the previous control for varied effects. Complex to master but offers more control
          enum:
          - automatic
          - composition
          - straight
          - smooth_in
          - smooth_out
          - smooth_both
          - reverse_both
          - soft_in
          - soft_out
          - soft_mid
          - strong_mid
          - style_shift
          - strong_shift
          type: string
        fixed_generation:
          default: false
          description: 'When this option is enabled, using the same settings will consistently produce the same image. Fixed generations are ideal for fine-tuning, as it allows for incremental changes to parameters (such as the prompt) to see subtle variations in the output. When disabled, expect each generation to introduce a degree of randomness, leading to more diverse outcomes.

            '
          type: boolean
      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:
      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
  examples:
    200-tasks-list:
      summary: Success - Return all tasks
      value:
        data:
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee92
          status: COMPLETED
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee93
          status: COMPLETED
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee93
          status: CREATED
    200-task-in-progress:
      summary: Success - Task in progress
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
    request-image-relight-required-params:
      summary: Example - Relight only required params
      value:
        image: iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABrElEQVR4nO3BMQEAAADCoPVPbQ0Po...
    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
    request-image-relight-all-params:
      summary: Example - Relight request with all params
      value:
        image: iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABrElEQVR4nO3BMQEAAADCoPVPbQ0Po...
        prompt: A sunlit forest clearing at golden hour
        transfer_light_from_reference_image: iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABrElEQVR4nO3BMQEAAADCoPVPbQ0Po...
        light_transfer_strength: 100
        interpolate_from_original: false
        change_background: true
        style: smooth
        advanced_settings:
          whites: 60
          blacks: 60
          brightness: 30
          contrast: 40
          saturation: 50
          engine: illusio
          transfer_light_a: low
          transfer_light_b: soft_in
          fixed_generation: true
  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)