> ## 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 from a text prompt using OpenAI's GPT Image 2.5 model.

**Key Features:**
- Strong instruction following on long, detailed prompts
- Reliable text rendering inside the image
- Explicit resolution tier, aspect ratio, format and compression control
- Selectable quality tier (`low` / `medium` / `high`)

**Best for:**
- Marketing and editorial images that must contain legible text
- Prompts with many precise constraints
- Cases where transparency or an exact output format is required

**Output:** one image per `num_images` (up to 10), at the size selected
by `resolution` + `aspect_ratio`, delivered as CDN URLs in the task's
`generated` array.

**Credits:** the `quality` tier sets the price per image and
`resolution` multiplies it (`1k` x1, `2k` x2, `4k` x3). Every image in
`num_images` is billed.

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/text-to-image/gpt-image-2-5
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/text-to-image/gpt-image-2-5:
    post:
      tags:
        - text-to-image
      summary: Create image from text - GPT Image 2
      description: |
        Generate images from a text prompt using OpenAI's GPT Image 2.5 model.

        **Key Features:**
        - Strong instruction following on long, detailed prompts
        - Reliable text rendering inside the image
        - Explicit resolution tier, aspect ratio, format and compression control
        - Selectable quality tier (`low` / `medium` / `high`)

        **Best for:**
        - Marketing and editorial images that must contain legible text
        - Prompts with many precise constraints
        - Cases where transparency or an exact output format is required

        **Output:** one image per `num_images` (up to 10), at the size selected
        by `resolution` + `aspect_ratio`, delivered as CDN URLs in the task's
        `generated` array.

        **Credits:** the `quality` tier sets the price per image and
        `resolution` multiplies it (`1k` x1, `2k` x2, `4k` x3). Every image in
        `num_images` is billed.

        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_gpt_image_2_5
      requestBody:
        content:
          application/json:
            examples:
              required-params:
                $ref: '#/components/examples/request-gpt-image-2-5-required-params'
              all-params:
                $ref: '#/components/examples/request-gpt-image-2-5-all-params'
            schema:
              $ref: '#/components/schemas/ttigi25-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 GPT Image 2.5 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-gpt-image-2-5-required-params:
      description: >
        Only `prompt` is required; everything else falls back to its default
        (1k,

        `aspect_ratio: auto` so the model picks the shape, medium quality, png,

        `flare`).
      summary: Minimum request
      value:
        prompt: >-
          A vintage travel poster for Mars, bold sans-serif title, muted orange
          palette
    request-gpt-image-2-5-all-params:
      description: >
        A 2K widescreen batch of three JPEGs rendered by the editing-precision
        model.

        Billed as quality tier x resolution multiplier x num_images — here
        medium x2

        x3. Note that `xhigh` and `max` are currently billed at the `high`
        price.
      summary: Every parameter
      value:
        prompt: >-
          A vintage travel poster for Mars, bold sans-serif title reading VISIT
          MARS, muted orange palette, subtle grain
        num_images: 3
        variant: sunburst
        resolution: 2k
        aspect_ratio: widescreen_16_9
        quality: medium
        output_format: jpeg
        output_compression: 85
        background: opaque
        moderation: auto
        webhook_url: https://www.example.com/webhook
    200-task-in-progress:
      summary: Success - Task in progress
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
  schemas:
    ttigi25-request-content:
      properties:
        prompt:
          description: >
            Text description of the image you want to generate.


            **Tips:**

            - GPT Image 2.5 follows long, detailed instructions well

            - Text to render inside the image can be given verbatim, in quotes

            - Precise constraints (colours, layout, camera) are respected
            closely


            **Examples:**

            - Simple: "A vintage travel poster for Mars"

            - Detailed: "A vintage travel poster for Mars, bold sans-serif title
            reading VISIT MARS, muted orange palette, grain"
          example: >-
            A vintage travel poster for Mars, bold sans-serif title, muted
            orange palette
          maxLength: 32000
          minLength: 1
          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
        num_images:
          default: 1
          description: |
            How many images to generate for this prompt. **Each image is billed
            separately.**
          example: 1
          maximum: 10
          minimum: 1
          type: integer
        variant:
          default: flare
          description: >
            Which model of the GPT Image 2.5 line renders the request. Both
            share

            every other parameter, the quality scale and the price.

            - `flare`: optimised for latency (default)

            - `sunburst`: optimised for editing precision
          enum:
            - flare
            - sunburst
          example: flare
          type: string
        resolution:
          default: 1k
          description: >
            Resolution tier of the generated image. Combined with `aspect_ratio`
            it

            selects the exact pixel size.


            With `aspect_ratio: auto`, only `1k` leaves the size to the model;
            `2k`

            and `4k` render a square at that tier.


            **Credits:** the tier multiplies the price set by `quality` — `1k`
            x1,

            `2k` x2, `4k` x3. On the edit endpoint it does not affect the price.
          enum:
            - 1k
            - 2k
            - 4k
          example: 1k
          type: string
        aspect_ratio:
          default: auto
          description: >
            Shape of the generated image, expressed as *_width_height (e.g.

            `square_1_1`, `widescreen_16_9`).


            `auto` (the default) lets the model choose the shape. When the
            request

            carries `reference_images`, the output keeps **their** aspect ratio,

            including ratios that are not in this list — which is what makes
            `auto`

            the right choice for editing a picture whose proportions must be

            preserved.
          enum:
            - auto
            - square_1_1
            - classic_4_3
            - traditional_3_4
            - widescreen_16_9
            - social_story_9_16
            - film_horizontal_21_9
            - standard_3_2
            - portrait_2_3
            - horizontal_2_1
            - banner_3_1
          example: auto
          type: string
        quality:
          default: medium
          description: >
            Render quality tier. Higher tiers spend more provider compute; lower

            tiers are faster.

            - `low`: fastest, for drafts and iteration

            - `medium`: balanced (default)

            - `high`: high detail and prompt adherence

            - `xhigh`, `max`: the extended tiers of GPT Image 2.5, for the most
              demanding renders

            **Credits:** `low`, `medium` and `high` are billed on their own
            tier.

            `xhigh` and `max` are currently billed at the `high` price.
          enum:
            - low
            - medium
            - high
            - xhigh
            - max
          example: medium
          type: string
        output_format:
          default: png
          description: >
            The file format of the generated image.

            - `png`: lossless, supports transparency. Best for logos, text and
            sharp edges

            - `jpeg`: compressed, no transparency. Smallest files for
            photographic content

            - `webp`: compressed, supports transparency


            `output_compression` only applies to `jpeg` and `webp`. A `jpeg`
            output

            cannot carry an alpha channel, so it is rejected when `background`
            is

            `transparent`.
          enum:
            - png
            - jpeg
            - webp
          example: png
          type: string
        background:
          description: >
            How the image background is produced.

            - `transparent`: render without a background. Requires an
            `output_format`
              with an alpha channel (`png` or `webp`)
            - `opaque`: always render a filled background

            - `auto`: let the model decide


            When omitted, the provider default applies.
          enum:
            - transparent
            - opaque
            - auto
          example: auto
          type: string
        output_compression:
          description: |
            Compression level for the generated image, where 100 is the least
            compressed. Only applies when `output_format` is `jpeg` or `webp`;
            ignored for `png`.
          example: 80
          maximum: 100
          minimum: 0
          type: integer
        moderation:
          default: auto
          description: |
            Strictness of the model provider's own content filter.
            - `auto`: the provider's standard filtering (default)
            - `low`: less restrictive filtering

            This is the model provider's filter and is applied in addition to
            Freepik's platform moderation, which cannot be disabled.
          enum:
            - auto
            - low
          example: auto
          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

````