---
title: "Create image from text - Magnific One"
method: POST
path: "/v1/ai/magnific-one"
tags: ["text-to-image"]
---

# Create image from text - Magnific One

`POST /v1/ai/magnific-one`

## Request

- Base URL: `https://api.magnific.com`
- URL: `https://api.magnific.com/v1/ai/magnific-one`
- Auth: API key in header `x-magnific-api-key`

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

## Request body

- MagnificOneRequestContent
  - `prompt` string, required: 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"
  - `mode` 'quality' | 'draft': 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.
  - `aspect_ratio` '1:1' | '2:1' | '3:1' | '2:3' | '3:2' | '3:4' | '4:3' | '16:9' | '9:16' | '21:9': 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.
  - `quality` 'medium' | 'high': 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.
  - `resolution` '1k' | '2k' | '4k': 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.
  - `tiles` 8 | 16: 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
  - `reference_images` string[]: Optional reference images that guide the style of the result. Supported in both modes. They do not change the price.
  - `webhook_url` string, uri: 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.

## Response `200`

OK - The request has succeeded and the Magnific One process has started.

- GetStyleTransferTaskStatus200Response
  - `data` TaskDetail, required
    - `task_id` string, uuid, required: Task identifier
    - `status` 'CREATED' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED', required: Task status
    - `generated` string[], required

## Other responses

- `400`: Bad Request - The server could not understand the request due to invalid syntax.
- `401`: Unauthorized - The client must authenticate itself to get the requested response.
- `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
- `503`: Service Unavailable

---

[API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)