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

# Create Image

> Generate images with Magnific One, Magnific's image model with art
direction built in: from a prompt, it develops the composition, style,
lighting and visual treatment before rendering.

**Modes:**
- `quality` (default): one finished image, with selectable `quality`
  and `resolution` (up to 4k)
- `draft`: a contact sheet of quick variations, returned as 8 or 16
  individual images — explore directions, then render the chosen one
  in `quality` mode

**Key Features:**
- Art direction from a short prompt
- Optional style reference images (up to 10), in both modes
- 10 aspect ratios, from `21:9` to `9:16`

**Output:** the task's `generated` array holds one image URL in
`quality` mode, or 8 or 16 URLs (one per individual image) in `draft`
mode.

**Credits:** a `quality` request is billed once, at the price of its
`quality` and `resolution`. A `draft` request is billed once for the
whole sheet, at the `medium` / `2k` price, never per image. Reference
images do not change the price.

The request is processed asynchronously: the endpoint returns a task id
immediately. Retrieve the result by polling the task endpoint or by
providing an optional `webhook_url`.




## OpenAPI

````yaml POST /v1/ai/magnific-one
openapi: 3.0.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 API
  version: 1.0.0
servers:
  - description: B2B API Production V1
    url: https://api.magnific.com
security:
  - magnificApiKey: []
paths:
  /v1/ai/magnific-one:
    post:
      tags:
        - text-to-image
      summary: Create image from text - Magnific One
      description: |
        Generate images with Magnific One, Magnific's image model with art
        direction built in: from a prompt, it develops the composition, style,
        lighting and visual treatment before rendering.

        **Modes:**
        - `quality` (default): one finished image, with selectable `quality`
          and `resolution` (up to 4k)
        - `draft`: a contact sheet of quick variations, returned as 8 or 16
          individual images — explore directions, then render the chosen one
          in `quality` mode

        **Key Features:**
        - Art direction from a short prompt
        - Optional style reference images (up to 10), in both modes
        - 10 aspect ratios, from `21:9` to `9:16`

        **Output:** the task's `generated` array holds one image URL in
        `quality` mode, or 8 or 16 URLs (one per individual image) in `draft`
        mode.

        **Credits:** a `quality` request is billed once, at the price of its
        `quality` and `resolution`. A `draft` request is billed once for the
        whole sheet, at the `medium` / `2k` price, never per image. Reference
        images do not change the price.

        The request is processed asynchronously: the endpoint returns a task id
        immediately. Retrieve the result by polling the task endpoint or by
        providing an optional `webhook_url`.
      operationId: create_image_from_text_magnific_one
      requestBody:
        content:
          application/json:
            examples:
              required-params:
                $ref: '#/components/examples/request-magnific-one-required-params'
              all-params:
                $ref: '#/components/examples/request-magnific-one-all-params'
              draft:
                $ref: '#/components/examples/request-magnific-one-draft'
            schema:
              $ref: '#/components/schemas/magnific-one-request-content'
        required: true
      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 Magnific One 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'
components:
  examples:
    request-magnific-one-required-params:
      description: |
        Only `prompt` is required; everything else falls back to its default
        (`quality` mode, `high` quality, `2k`, `1:1`).
      summary: Minimum request
      value:
        prompt: A lighthouse on a cliff at dusk
    request-magnific-one-all-params:
      description: >
        One 4k widescreen image in `quality` mode, guided by two style
        references.

        Billed once at the `high` / `4k` price; the references do not change it.
      summary: Every parameter
      value:
        prompt: >-
          Editorial photo of a lighthouse on a basalt cliff at dusk, long
          exposure sea, warm window light
        mode: quality
        quality: high
        resolution: 4k
        aspect_ratio: '16:9'
        reference_images:
          - https://example.com/style-reference-1.jpg
          - https://example.com/style-reference-2.jpg
        webhook_url: https://www.example.com/webhook
    request-magnific-one-draft:
      description: >
        Sixteen quick variations, each exactly `3:4`. `quality` and `resolution`
        are

        ignored in `draft` mode; the whole sheet is billed once, at the `medium`
        /

        `2k` price.
      summary: Draft contact sheet
      value:
        prompt: Poster concepts for a jazz festival by the sea
        mode: draft
        tiles: 16
        aspect_ratio: '3:4'
    200-task-in-progress:
      summary: Success - Task in progress
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
  schemas:
    magnific-one-request-content:
      additionalProperties: false
      properties:
        prompt:
          description: >
            Text description of the image you want to generate. Magnific One

            develops the art direction (composition, style, lighting and visual

            treatment) from it before rendering.


            **Examples:**

            - Simple: "A lighthouse on a cliff at dusk"

            - Detailed: "Editorial photo of a lighthouse on a basalt cliff at
            dusk, long exposure sea, warm window light, cinematic framing"
          example: A lighthouse on a cliff at dusk
          maxLength: 2000
          minLength: 1
          type: string
        mode:
          default: quality
          description: |
            What the request produces.
            - `quality`: one finished image (default)
            - `draft`: a contact sheet of quick variations, returned as 8 or 16
              individual images (see `tiles`). Use it to explore directions before
              rendering the chosen one in `quality` mode.
          enum:
            - quality
            - draft
          example: quality
          type: string
        aspect_ratio:
          default: '1:1'
          description: >
            Aspect ratio of the image. In `draft` mode it describes each
            individual

            image, not the contact sheet.


            With `tiles: 16` every ratio is honoured exactly. With `tiles: 8`
            the

            sheet is twice as wide relative to its images, and the ratios that
            no

            longer fit are approximated to the closest supported one: `1:1`,
            `2:3`,

            `3:2` and `3:4` come back exact, the rest may deviate. Use `tiles:
            16`

            when the ratio of every image must be exact.
          enum:
            - '1:1'
            - '2:1'
            - '3:1'
            - '2:3'
            - '3:2'
            - '3:4'
            - '4:3'
            - '16:9'
            - '9:16'
            - '21:9'
          example: '1:1'
          type: string
        quality:
          default: high
          description: |
            Render quality in `quality` mode.
            - `medium`: faster and cheaper
            - `high`: maximum detail (default)

            Ignored in `draft` mode, which always renders at `medium`.

            **Credits:** together with `resolution`, it sets the price of the
            request.
          enum:
            - medium
            - high
          example: high
          type: string
        resolution:
          default: 2k
          description: >
            Resolution tier of the image in `quality` mode. Combined with

            `aspect_ratio` it selects the exact pixel size.


            Ignored in `draft` mode, which always renders its contact sheet at
            `2k`.


            **Credits:** together with `quality`, it sets the price of the
            request.
          enum:
            - 1k
            - 2k
            - 4k
          example: 2k
          type: string
        tiles:
          default: 8
          description: |
            Number of individual images returned in `draft` mode. Ignored in
            `quality` mode.
            - `8`: a 2x4 sheet (default). May approximate `aspect_ratio`
            - `16`: a 4x4 sheet. Always preserves `aspect_ratio` exactly
          enum:
            - 8
            - 16
          example: 8
          type: integer
        reference_images:
          description: |
            Optional reference images that guide the style of the result.
            Supported in both modes. They do not change the price.
          items:
            description: Publicly accessible image URL.
            example: https://example.com/reference.jpg
            type: string
          maxItems: 10
          minItems: 1
          type: array
        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
      required:
        - prompt
      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
    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
    inline_object:
      example:
        message: message
      properties:
        message:
          type: string
      type: object
    inline_object_1:
      properties:
        problem:
          $ref: '#/components/schemas/inline_object_1_problem'
      type: object
    inline_object_2:
      example:
        message: Internal Server Error
      properties:
        message:
          example: Internal Server Error
          type: string
      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
    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_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_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
  responses:
    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.
    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.
    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.
    503-service-unavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_object_3'
      description: Service Unavailable
  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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.