Freepik Mystic 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 Mystic API
  version: 1.0.0
servers:
- description: B2B API Production V1
  url: https://api.magnific.com
security:
- magnificApiKey: []
tags:
- name: mystic
paths:
  /v1/ai/mystic:
    get:
      description: Get the status of all Mystic 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 Mystic 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: Mystic - List tasks
      tags:
      - mystic
      operationId: getV1AiMystic
      x-operation-id-source: derived
    post:
      description: Convert descriptive text input into images using AI. This endpoint accepts a variety of parameters to customize the generated images.
      operationId: create_image_mystic
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/mystic-request'
      responses:
        '200':
          content:
            application/json:
              examples:
                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 request has succeeded and the Mystic 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: Mystic - Create image from text
      tags:
      - mystic
  /v1/ai/mystic/{task-id}:
    get:
      description: Get the status of the Mystic task
      operationId: get_mystic_task_status
      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-mystic-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: Mystic - Get task status
      tags:
      - mystic
components:
  schemas:
    colors_palette_inner:
      properties:
        color:
          description: Hex color code
          example: '#FF0000'
          pattern: ^#[0-9A-F]{6}$
          type: string
        weight:
          description: Weight of the color (0.05 to 1)
          example: 0.5
          maximum: 1
          minimum: 0.05
          type: number
      required:
      - color
      - weight
      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
    mystic_request_styling_characters_inner:
      properties:
        id:
          description: 'ID of the character to modify.

            **This ID can be found in the `v1/ai/loras` endpoint.**

            '
          type: string
        strength:
          default: 100
          description: 'Strength of the character to apply. The higher the value, the more the character will be applied to the image.

            If ID is not set, the strength will be applied to the character specified in the `prompt` field.


            Valid values range `[0, 200]`. Default value is `100`.

            '
          maximum: 200
          minimum: 0
          type: number
      required:
      - strength
      type: object
    inline_object_1:
      properties:
        problem:
          $ref: '#/components/schemas/inline_object_1_problem'
      type: object
    mystic_request_styling:
      description: Styling options for the image
      properties:
        styles:
          items:
            $ref: '#/components/schemas/mystic_request_styling_styles_inner'
          maxItems: 1
          type: array
        characters:
          description: Modify the characters introduced in the `prompt` field adjusting their strength
          items:
            $ref: '#/components/schemas/mystic_request_styling_characters_inner'
          maxItems: 1
          type: array
        colors:
          description: Dominant colors to generate the image
          items:
            $ref: '#/components/schemas/colors_palette_inner'
          maxItems: 5
          minItems: 1
          type: array
      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
    mystic_request_styling_styles_inner:
      properties:
        name:
          description: 'Name of the style to apply.

            **The name of the style can be found in the `v1/ai/loras` endpoint.**

            '
          type: string
        strength:
          default: 100
          description: 'Strength of the style to apply. The higher the value, the more the style will be applied to the image. Some styles may not be affected by this parameter.


            Valid values range `[0, 200]`. Default value is `100`.

            '
          maximum: 200
          minimum: 0
          type: number
      required:
      - name
      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
    mystic-request:
      description: "### Model Compatibility and LoRA Usage\n\nThe Mystic API supports different model configurations with varying LoRA compatibility:\n\n**LoRA-Compatible Configuration:**\n- Use the default model (no `model` field specified)\n- No `structure_reference` or `style_reference` provided\n- LoRAs can be used via:\n  - Character syntax in prompt: `@character_name` or `@character_name::strength`\n  - `styling.characters` array\n  - `styling.styles` array\n\n**LoRA-Incompatible Configurations:**\n- **Specific Models**: `fluid`, `flexible` , `super_real` and `editorial_portraits` models ignore all LoRAs\n- **Structure Reference**: When `structure_reference` is provided, LoRAs are ignored\n- **Style Reference**: When `style_reference` is provided, LoRAs are ignored\n- **Combined References**: When both `structure_reference` and `style_reference` are provided, LoRAs are ignored\n\n**Important**: The API will not return errors for incompatible combinations. Instead, LoRAs will be silently ignored, and the request will proceed with the selected model configuration.\n"
      properties:
        prompt:
          description: "### AI Model Prompt Description\n\nThe prompt is a short text that describes the image you want to generate. It can range from simple descriptions, like `\"a cat\"`, to detailed scenarios, such as `\"a cat with wings, playing the guitar, and wearing a hat\"`. If no prompt is provided, the AI will generate a random image.\n\n#### Adding Characters to the Prompt\nYou can introduce characters into the prompt using the following syntax:\n- `@character_name`: Represents the character you want to include.\n  Example: `My friend @john is a great artist.`\n\n#### Modifying Character Strength\nTo adjust the influence or \"strength\" of a character in the image, use the following syntax:\n- `@character_name::strength`: Specify the character's strength by appending `::strength` to their name, where `strength` is a numerical value.\n  Example: `My friend @john::200 is a great artist.`\n\nHigher strength values will make the character more prominent in the generated image.\n"
          type: string
        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
        structure_reference:
          description: '### Structure Reference

            Base64 image to use as structure reference. Using images as structure references allows you to influence the shape of your final image. This feature enables various creative applications such as coloring sketches, transforming cartoons into realistic images, texturing basic 3D models, or converting real images into cartoons. The outcome is entirely controlled by your prompt, offering limitless creative possibilities.

            '
          format: byte
          type: string
        structure_strength:
          default: 50
          description: 'Note: This parameter only takes effect when a `"structure_reference"` image is provided.

            Allows to maintain the structure of the original image.

            '
          maximum: 100
          minimum: 0
          type: integer
        style_reference:
          description: '### Style Reference

            Base64 image to use as style reference. Using images as style references allows you to influence the aesthetic of your creation. This is possibly the most powerful tool of Mystic, as it truly lets you create incredibly unique images.

            '
          format: byte
          type: string
        adherence:
          default: 50
          description: 'Note: This parameter only takes effect when a `"style_reference"` image is provided.

            Increasing this value will make your generation more faithful to the prompt, but it may transfer the style a bit less accurately. Higher values can help fix small artifacts, anatomical errors and text readability. Lower values will give you more creative images and closer to the style reference.

            '
          maximum: 100
          minimum: 0
          type: integer
        hdr:
          default: 50
          description: 'Note: This parameter only takes effect when a `"style_reference"` image is provided.

            Increasing this value can give you a more detailed image, at the cost of a more ''AI look'' and slightly worse style transfer. Lower values have a more natural and artistic look but may increase artifacts.

            '
          maximum: 100
          minimum: 0
          type: integer
        resolution:
          default: 2k
          description: Resolution of the image
          enum:
          - 1k
          - 2k
          - 4k
          type: string
        aspect_ratio:
          default: square_1_1
          description: 'Image size with the aspect ratio. The aspect ratio is the proportional relationship between an image''s width and height, expressed as *_width_height (e.g., square_1_1, widescreen_16_9). It is calculated by dividing the width by the height.\

            If not present, the default is `square_1_1`.

            Note: For the `fluid` model, only this values are valid:

            * square_1_1

            * social_story_9_16

            * widescreen_16_9

            * traditional_3_4

            * classic_4_3

            '
          enum:
          - square_1_1
          - classic_4_3
          - traditional_3_4
          - widescreen_16_9
          - social_story_9_16
          - smartphone_horizontal_20_9
          - smartphone_vertical_9_20
          - standard_3_2
          - portrait_2_3
          - horizontal_2_1
          - vertical_1_2
          - social_5_4
          - social_post_4_5'
          example: square_1_1
          type: string
        model:
          default: realism
          description: '* `zen` - for smoother, basic, and cleaner results. Fewer objects in the scene and less intricate details. The softer looking one.


            * `flexible` - good prompt adherence. However, it has results that are a bit more HDR and saturated than Realism or Fluid. It''s especially good with illustrations, fantastical prompts, and for diving into the latent space in search of very specific visual styles.


            * `fluid` - the model that adheres best to prompts with great average quality for all kind of images. It can generate really creative images! It will always follow your input no matter what.


            * `realism` - with a more realistic color palette. It tries to give an extra boost of reality to your images, a kind of "less AI look". Works especially well with photographs but also magically works with illustrations too. IMPORTANT: you should use Zen, Flexible or Fluid if you are trying to generate something that is really fantastic or a known character, Realism may not follow your prompt well.


            * `super_real` - if reality is your priority, this is your model. Nearly as versatile as Flexible, it excels in realism outperforming Editorial Portraits in medium shots, though not as strong for close-ups.


            * `editorial_portraits` - the most amazing state-of-the-art generator for editorial portraits. You have never seen a level of realism like this before. Perfect for hyperrealistic close-up or medium shots. Unfortunately, in wide or distant shots, it generates anatomical problems and artifacts... but for close-ups, it is simply the best on the market. Tip: use the longest and most explanatory prompts possible, they really suit it well!

            '
          enum:
          - realism
          - fluid
          - zen
          - flexible
          - super_real
          - editorial_portraits
          type: string
        creative_detailing:
          default: 33
          description: 'Higher values can achieve greater detail per pixel at higher resolutions at the cost of giving a somewhat more "HDR" or artificial look.

            Very high values can generate quite crazy things like eyes where they shouldn''t appear, etc.


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

            '
          maximum: 100
          minimum: 0
          type: integer
        engine:
          default: automatic
          description: "Select the engine for the AI model. Available options:\n  * `automatic` - default choice\n  * `Illusio` - for smoother illustrations, landscapes, and nature. The softer looking one.\n  * `Sharpy` - better for realistic images like photographs and for a more grainy look. It provides the sharpest and most detailed images. If you use it for illustrations it will give them more texture and a less softer look.\n  * `Sparkle` - also good for realistic images. It's a middle ground between Illusio and Sharpy.\n"
          enum:
          - automatic
          - magnific_illusio
          - magnific_sharpy
          - magnific_sparkle
          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
        filter_nsfw:
          default: true
          description: 'Controls **NSFW** (Not Safe For Work) content filtering during generation.


            This parameter is always set to `true` by default and NSFW filtering **cannot be disabled** for standard API usage. Only authorized clients with special permissions can disable this filter.


            **Important:** If your use case requires disabling NSFW filtering, please contact our support team to discuss your requirements and potential authorization.

            '
          type: boolean
        styling:
          $ref: '#/components/schemas/mystic_request_styling'
      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
  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.
  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-mystic-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
          has_nsfw:
          - false
    200-task-in-progress:
      summary: Success - Task in progress
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
  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)