Skip to main content
POST

Authorizations

​
x-magnific-api-key
string
header
required

Your Magnific API key. Required for authentication. Learn how to obtain an API key

Body

application/json
​
prompt
string
required

Text description of the image you want to generate.

Tips:

  • Recraft's strength is rendering legible text inside the image, so spell out any wording the design must contain
  • Describe layout, palette and typography, not just the subject

Examples:

  • Simple: "A storefront sign that reads OPEN DAILY 9AM"
  • Detailed: "A storefront sign that reads OPEN DAILY 9AM, flat vector poster style, cream and navy palette, bold rounded display type"
Required string length: 1 - 10000
Example:

"A storefront sign that reads OPEN DAILY 9AM, flat vector poster style"

​
aspect_ratio
enum<string>
default:square_1_1

Aspect ratio of the generated image, expressed as *_width_height.

Recraft renders from a fixed set of sizes, so the output dimensions are the ones listed below and are not always the exact mathematical ratio the name suggests — widescreen_16_9 renders 1344x768, which is 7:4.

Available options:
square_1_1,
horizontal_2_1,
vertical_1_2,
standard_3_2,
portrait_2_3,
classic_4_3,
traditional_3_4,
social_5_4,
social_post_4_5,
widescreen_16_9,
social_story_9_16
Example:

"square_1_1"

​
tier
enum<string>
default:mid

Quality tier, which selects both the price and the output size.

  • mid: the V4 sizes listed under aspect_ratio (default)
  • pro: twice the linear dimensions, four times the pixels

Credits: mid is billed as Recraft V4 and pro as Recraft V4 Pro.

Available options:
mid,
pro
Example:

"mid"

​
variant
enum<string>
default:standard

How much art direction the model applies on top of the prompt.

  • standard: the model adds its own visual judgement — palette, decoration, display typography (default)
  • utility: a literal, neutral render with no invented colour or ornament. Use it for diagrams, wireframes, UI mockups and any asset that must follow the prompt exactly

Does not affect the price.

Available options:
standard,
utility
Example:

"standard"

​
enhance_prompt
boolean
default:true

Rewrite the prompt with an LLM before generating, which generally produces a richer design. Any text the image must render is preserved verbatim.

Set it to false to send the prompt exactly as written, which is what you want when you need a deterministic input.

Example:

true

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

Example:

"https://www.example.com/webhook"

Response

OK - The request has succeeded and the Recraft V4.1 process has started.

​
data
object
required
Example: