> ## 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.

# Magnific One – Text-to-Image API | Magnific API

> Generate images with Magnific One, the image model with art direction built in. A finished image up to 4k, or a draft contact sheet of 8 or 16 variations.

<Card title="Magnific One" icon="wand-magic-sparkles">
  The image model with art direction built in: it develops composition, style, lighting and visual treatment from your prompt before rendering.
</Card>

Magnific One is a text-to-image API that turns a short prompt into an art-directed image. Instead of rendering the prompt literally, it first decides how the image should look — framing, style, light and treatment — and then renders it. You keep the creative control: explore directions with a quick draft, pick the one you want and render it at full quality.

### Key capabilities

* **Art direction from a short prompt**: describe the subject and the intent; Magnific One develops the composition, style, lighting and visual treatment
* **Two modes in one endpoint**: `mode: "quality"` returns one finished image; `mode: "draft"` returns a contact sheet of quick variations as 8 or 16 individual images
* **Up to 4k**: in `quality` mode, choose `resolution` `1k`, `2k` or `4k` and `quality` `medium` or `high`
* **Style references**: guide the look with up to 10 `reference_images`, in both modes, at no extra cost
* **10 aspect ratios**: from `21:9` to `9:16`, including `3:1` banners
* **Async processing**: every request returns a task ID immediately. Poll the task endpoint or supply `webhook_url` to be notified on completion

### Use cases

* **Campaign key visuals**: art-directed images from a one-line brief
* **Concept exploration**: a `draft` sheet of 16 directions in one call, then a `quality` render of the winner
* **Editorial and social content**: consistent visual treatment across a series using the same style references
* **Banners and covers**: wide formats such as `21:9` and `3:1`

### Generate images with Magnific One

Submit a prompt to create a generation task. The API responds with a task ID; collect the result by polling or via webhook.

<div className="my-11">
  <Columns cols={2}>
    <Card title="POST /v1/ai/magnific-one" icon="wand-magic-sparkles" href="/api-reference/text-to-image/magnific-one/generate">
      Create a new image generation task
    </Card>

    <Card title="GET /v1/ai/magnific-one" icon="list" href="/api-reference/text-to-image/magnific-one/magnific-one-tasks">
      List all Magnific One tasks with status
    </Card>

    <Card title="GET /v1/ai/magnific-one/{task-id}" icon="magnifying-glass" href="/api-reference/text-to-image/magnific-one/task-by-id">
      Get task status and results by ID
    </Card>
  </Columns>
</div>

### Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `prompt` | `string` | Yes | - | Text description of the image to generate, up to 2,000 characters |
| `mode` | `string` | No | `quality` | `quality` for one finished image, or `draft` for a contact sheet of variations |
| `quality` | `string` | No | `high` | `medium` or `high`. `quality` mode only; `draft` always renders at `medium` |
| `resolution` | `string` | No | `2k` | `1k`, `2k` or `4k`. `quality` mode only; `draft` always renders its sheet at `2k` |
| `aspect_ratio` | `string` | No | `1:1` | `1:1`, `2:1`, `3:1`, `2:3`, `3:2`, `3:4`, `4:3`, `16:9`, `9:16` or `21:9`. In `draft` mode it applies to each individual image |
| `tiles` | `integer` | No | `8` | `8` or `16` images per draft sheet. `draft` mode only |
| `reference_images` | `string[]` | No | - | 1 to 10 publicly accessible image URLs that guide the style. Supported in both modes |
| `webhook_url` | `string` | No | - | URL called when the task completes |

### Output

When the task is `COMPLETED`, its `generated` array holds:

* **`quality` mode**: one image URL
* **`draft` mode**: 8 or 16 image URLs, one per variation, already cut out of the contact sheet

### Pricing

* 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, whether you ask for 8 or 16
* **Reference images** do not change the price

See the [Pricing page](/pricing) for current rates.

The endpoint reference pages above are generated from the OpenAPI specification and are the authoritative, complete parameter list.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What is Magnific One and how does it work?">
    Magnific One is Magnific's image model with art direction built in. You submit a prompt and receive a task ID immediately; Magnific One develops the direction of the image and renders it. Poll the task endpoint or configure a webhook to receive the result when processing completes.
  </Accordion>

  <Accordion title="When should I use draft mode?">
    Use `draft` to explore. One request returns 8 or 16 variations of your prompt, billed once as a single `medium` / `2k` render. Pick the direction you like and render it in `quality` mode at the resolution you need.
  </Accordion>

  <Accordion title="Why do some draft images not match my aspect ratio exactly?">
    With `tiles: 8` the variations are laid out as a 2x4 sheet, which is twice as wide relative to each image. Some ratios no longer fit and are approximated to the closest supported one: `1:1`, `2:3`, `3:2` and `3:4` come back exact, the rest may deviate. With `tiles: 16` (a 4x4 sheet) every ratio is honoured exactly, so use it when the shape matters.
  </Accordion>

  <Accordion title="Are quality and resolution used in draft mode?">
    No. `draft` always renders its sheet at `medium` quality and `2k`, so its price does not depend on them. They are accepted and ignored.
  </Accordion>

  <Accordion title="What do reference images do?">
    They guide the style of the result: palette, treatment, mood. You can send up to 10 publicly accessible image URLs, in either mode. They do not change the price.
  </Accordion>

  <Accordion title="What are the rate limits for Magnific One?">
    Rate limits depend on your subscription tier. See [Rate Limits](/ratelimits) for current limits.
  </Accordion>

  <Accordion title="How much does Magnific One cost?">
    A `quality` request costs the price of its `quality` and `resolution`; a `draft` request costs one `medium` / `2k` render for the whole sheet. See the [Pricing page](/pricing) for current rates.
  </Accordion>
</AccordionGroup>

## Best practices

* **Draft first, then render**: explore with `mode: "draft"` and `tiles: 16`, then re-run the chosen prompt in `quality` mode
* **Use `tiles: 16` when the ratio matters**: it is the only draft layout that keeps every aspect ratio exact
* **Keep prompts about intent**: describe the subject, mood and purpose; let Magnific One decide the composition and light
* **Reuse references for a series**: the same `reference_images` keep a consistent look across many generations
* **Production integration**: use `webhook_url` instead of polling for scalable applications
* **Error handling**: implement retry logic with exponential backoff for 503 errors

## Related APIs

* **[Mystic](/api-reference/mystic/mystic)**: Magnific's photorealistic image generation, with LoRA styles and characters
* **[Upscaler Creative](/api-reference/image-upscaler-creative/image-upscaler)**: add detail and resolution to a Magnific One render
* **[Image Expand](/api-reference/image-expand/post-flux-pro)**: extend an image beyond its original frame


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