Recraft V4.1 Pro API, Recraft V4 Pro API, Recraft V3 API: Pricing, Documentation

Authentication

All requests require an API key passed via header.

Request Parameters - Create Style

Reference Image Requirements

Limits that apply to every URL in image_urls.

Request Headers

Pricing — Create Style

Create Style is charged a flat rate per request. The number of reference images (1 to 10) does not change the price, and n is not a parameter on this endpoint.

Save the style_id you get back. Passing it as style_id on Text to Image and Text to Vector means you never pay for style creation again. Generating with style_reference_urls instead re-creates a style, and re-charges for it, on every call.

Response Handling

Common status codes for Recraft V4 Styles Create Style.

Error Responses

Validation runs before the request reaches the provider, so a 400 from this endpoint never costs you anything.

400 Bad Request — image_urls missing or out of range

{
  "error": "image_urls must be an array of 1 to 10 image URL strings.",
  "status": 400
}

400 Bad Request — image_weights does not line up with image_urls

{
  "error": "image_weights must contain exactly one weight per image_urls entry (image_urls: 2, image_weights: 1).",
  "status": 400
}

400 Bad Request — unsupported match value

{
  "error": "match must be one of: precise, flexible. \"regular\" is not supported by the Recraft V4 Styles models.",
  "status": 400
}

4xx — rejected by the provider

{
  "error": "The prompt could not be understood",
  "status": 422,
  "code": "invalid_prompt"
}

403 Insufficient Balance

"The balance is insufficient to proceed with this operation."

503 Service Unavailable — provider temporarily unavailable

{
  "error": "Image provider temporarily unavailable, please retry shortly",
  "status": 503
}

A 503 means the provider is down, rate-limited or out of capacity. It is not a problem with your request and retrying shortly is the right response.

Response Fields

Notes

The model is fixed by the endpoint you call. Any model key in your request body is dropped before the request is forwarded, so a request is always billed for the model it actually runs on. This endpoint responds synchronously — there is no queue and nothing to poll; the response carries the finished style. n is not accepted here: style creation is billed per request. A style created on this endpoint is intended for Text to Image and Text to Vector.

Authentication

All requests require an API key passed via header.

Request Parameters - Create Style Pro

Reference Image Requirements

Limits that apply to every URL in image_urls.

Request Headers

Pricing — Create Style Pro

Create Style Pro is charged a flat rate per request. The number of reference images (1 to 10) does not change the price, and n is not a parameter on this endpoint.

Save the style_id you get back. Passing it as style_id on Text to Image Pro and Text to Vector Pro means you never pay for style creation again. Generating with style_reference_urls instead re-creates a style, and re-charges for it, on every call.

Response Handling

Common status codes for Recraft V4 Styles Pro Create Style Pro.

Error Responses

Validation runs before the request reaches the provider, so a 400 from this endpoint never costs you anything.

400 Bad Request — image_urls missing or out of range

{
  "error": "image_urls must be an array of 1 to 10 image URL strings.",
  "status": 400
}

400 Bad Request — image_weights does not line up with image_urls

{
  "error": "image_weights must contain exactly one weight per image_urls entry (image_urls: 2, image_weights: 1).",
  "status": 400
}

400 Bad Request — unsupported match value

{
  "error": "match must be one of: precise, flexible. \"regular\" is not supported by the Recraft V4 Styles models.",
  "status": 400
}

4xx — rejected by the provider

{
  "error": "The prompt could not be understood",
  "status": 422,
  "code": "invalid_prompt"
}

403 Insufficient Balance

"The balance is insufficient to proceed with this operation."

503 Service Unavailable — provider temporarily unavailable

{
  "error": "Image provider temporarily unavailable, please retry shortly",
  "status": 503
}

A 503 means the provider is down, rate-limited or out of capacity. It is not a problem with your request and retrying shortly is the right response.

Response Fields

Notes

The model is fixed by the endpoint you call. Any model key in your request body is dropped before the request is forwarded, so a request is always billed for the model it actually runs on. This endpoint responds synchronously — there is no queue and nothing to poll; the response carries the finished style. n is not accepted here: style creation is billed per request. A style created on this endpoint is intended for Text to Image Pro and Text to Vector Pro.

Authentication

All requests require an API key passed via header.

Choosing a Style — style_id or style_reference_urls

Every generation needs exactly one style source. This is checked before the request leaves the gateway, so a malformed call costs you nothing.

Request Parameters - Text to Image

Reference Image Requirements

Limits that apply to every URL in style_reference_urls.

Request Headers

Pricing — Text to Image

Generation is charged per image: n images cost n times the per-image rate.

There is one surcharge, and it is easy to avoid. Sending style_reference_urls makes the provider build a style as part of this request, which adds one Create Style charge ($0.0055) on top — once per request, never multiplied by n. Sending a saved style_id adds nothing.

Every response carries style_id, including when the style was created implicitly from style_reference_urls. Save it and send it as style_id next time to drop the surcharge permanently.

Rates shown are the published rates for this endpoint at the time of writing; the pricing panel on this page is authoritative.

Response Handling

Common status codes for Recraft V4 Styles Text to Image.

Error Responses

Validation runs before the request reaches the provider, so a 400 from this endpoint never costs you anything.

400 Bad Request — no style source

{
  "error": "Exactly one of style_id or style_reference_urls is required. Send style_id to reuse a style you already created, or style_reference_urls (1 to 10 image URLs) to build one from reference images.",
  "status": 400
}

400 Bad Request — both style sources

{
  "error": "style_id and style_reference_urls are mutually exclusive - send exactly one of them, not both.",
  "status": 400
}

400 Bad Request — missing prompt

{
  "error": "prompt is required and must be a non-empty string.",
  "status": 400
}

400 Bad Request — n out of range

{
  "error": "n must not be greater than 6 (received 7).",
  "status": 400
}

400 Bad Request — unsupported style_match value

{
  "error": "style_match must be one of: precise, flexible. \"regular\" is not supported by the Recraft V4 Styles models.",
  "status": 400
}

4xx — rejected by the provider

{
  "error": "The prompt could not be understood",
  "status": 422,
  "code": "invalid_prompt"
}

403 Insufficient Balance

"The balance is insufficient to proceed with this operation."

503 Service Unavailable — provider temporarily unavailable

{
  "error": "Image provider temporarily unavailable, please retry shortly",
  "status": 503
}

A 503 means the provider is down, rate-limited or out of capacity. It is not a problem with your request and retrying shortly is the right response.

Response Fields

Notes

The model is fixed by the endpoint you call. Any model key in your request body is dropped before the request is forwarded, so a request is always billed for the model it actually runs on. This endpoint responds synchronously — there is no queue and nothing to poll; the response carries the finished result. Generation typically takes 20–60 seconds; larger n or larger sizes take longer.

Authentication

All requests require an API key passed via header.

Choosing a Style — style_id or style_reference_urls

Every generation needs exactly one style source. This is checked before the request leaves the gateway, so a malformed call costs you nothing.

Request Parameters - Text to Image Pro

Reference Image Requirements

Limits that apply to every URL in style_reference_urls.

Request Headers

Pricing — Text to Image Pro

Generation is charged per image: n images cost n times the per-image rate.

There is one surcharge, and it is easy to avoid. Sending style_reference_urls makes the provider build a style as part of this request, which adds one Create Style Pro charge ($0.0055) on top — once per request, never multiplied by n. Sending a saved style_id adds nothing.

Every response carries style_id, including when the style was created implicitly from style_reference_urls. Save it and send it as style_id next time to drop the surcharge permanently.

Rates shown are the published rates for this endpoint at the time of writing; the pricing panel on this page is authoritative.

Response Handling

Common status codes for Recraft V4 Styles Pro Text to Image Pro.

Error Responses

Validation runs before the request reaches the provider, so a 400 from this endpoint never costs you anything.

400 Bad Request — no style source

{
  "error": "Exactly one of style_id or style_reference_urls is required. Send style_id to reuse a style you already created, or style_reference_urls (1 to 10 image URLs) to build one from reference images.",
  "status": 400
}

400 Bad Request — both style sources

{
  "error": "style_id and style_reference_urls are mutually exclusive - send exactly one of them, not both.",
  "status": 400
}

400 Bad Request — missing prompt

{
  "error": "prompt is required and must be a non-empty string.",
  "status": 400
}

400 Bad Request — n out of range

{
  "error": "n must not be greater than 6 (received 7).",
  "status": 400
}

400 Bad Request — unsupported style_match value

{
  "error": "style_match must be one of: precise, flexible. \"regular\" is not supported by the Recraft V4 Styles models.",
  "status": 400
}

4xx — rejected by the provider

{
  "error": "The prompt could not be understood",
  "status": 422,
  "code": "invalid_prompt"
}

403 Insufficient Balance

"The balance is insufficient to proceed with this operation."

503 Service Unavailable — provider temporarily unavailable

{
  "error": "Image provider temporarily unavailable, please retry shortly",
  "status": 503
}

A 503 means the provider is down, rate-limited or out of capacity. It is not a problem with your request and retrying shortly is the right response.

Response Fields

Notes

The model is fixed by the endpoint you call. Any model key in your request body is dropped before the request is forwarded, so a request is always billed for the model it actually runs on. This endpoint responds synchronously — there is no queue and nothing to poll; the response carries the finished result. Generation typically takes 20–60 seconds; larger n or larger sizes take longer.

Authentication

All requests require an API key passed via header.

Choosing a Style — style_id or style_reference_urls

Every generation needs exactly one style source. This is checked before the request leaves the gateway, so a malformed call costs you nothing.

Request Parameters - Text to Vector

Reference Image Requirements

Limits that apply to every URL in style_reference_urls.

Request Headers

Pricing — Text to Vector

Generation is charged per image: n images cost n times the per-image rate.

There is one surcharge, and it is easy to avoid. Sending style_reference_urls makes the provider build a style as part of this request, which adds one Create Style charge ($0.0055) on top — once per request, never multiplied by n. Sending a saved style_id adds nothing.

Every response carries style_id, including when the style was created implicitly from style_reference_urls. Save it and send it as style_id next time to drop the surcharge permanently.

Rates shown are the published rates for this endpoint at the time of writing; the pricing panel on this page is authoritative.

Response Handling

Common status codes for Recraft V4 Styles Vector Text to Vector.

Error Responses

Validation runs before the request reaches the provider, so a 400 from this endpoint never costs you anything.

400 Bad Request — no style source

{
  "error": "Exactly one of style_id or style_reference_urls is required. Send style_id to reuse a style you already created, or style_reference_urls (1 to 10 image URLs) to build one from reference images.",
  "status": 400
}

400 Bad Request — both style sources

{
  "error": "style_id and style_reference_urls are mutually exclusive - send exactly one of them, not both.",
  "status": 400
}

400 Bad Request — missing prompt

{
  "error": "prompt is required and must be a non-empty string.",
  "status": 400
}

400 Bad Request — n out of range

{
  "error": "n must not be greater than 6 (received 7).",
  "status": 400
}

400 Bad Request — unsupported style_match value

{
  "error": "style_match must be one of: precise, flexible. \"regular\" is not supported by the Recraft V4 Styles models.",
  "status": 400
}

4xx — rejected by the provider

{
  "error": "The prompt could not be understood",
  "status": 422,
  "code": "invalid_prompt"
}

403 Insufficient Balance

"The balance is insufficient to proceed with this operation."

503 Service Unavailable — provider temporarily unavailable

{
  "error": "Image provider temporarily unavailable, please retry shortly",
  "status": 503
}

A 503 means the provider is down, rate-limited or out of capacity. It is not a problem with your request and retrying shortly is the right response.

Response Fields

Notes

The model is fixed by the endpoint you call. Any model key in your request body is dropped before the request is forwarded, so a request is always billed for the model it actually runs on. This endpoint responds synchronously — there is no queue and nothing to poll; the response carries the finished result. Output is SVG: output points to a .svg file served as image/svg+xml, which scales to any size without loss. image_format applies to raster output only and has no effect on this endpoint. Generation typically takes 20–60 seconds; larger n or larger sizes take longer.

Authentication

All requests require an API key passed via header.

Choosing a Style — style_id or style_reference_urls

Every generation needs exactly one style source. This is checked before the request leaves the gateway, so a malformed call costs you nothing.

Request Parameters - Text to Vector Pro

Reference Image Requirements

Limits that apply to every URL in style_reference_urls.

Request Headers

Pricing — Text to Vector Pro

Generation is charged per image: n images cost n times the per-image rate.

There is one surcharge, and it is easy to avoid. Sending style_reference_urls makes the provider build a style as part of this request, which adds one Create Style Pro charge ($0.0055) on top — once per request, never multiplied by n. Sending a saved style_id adds nothing.

Every response carries style_id, including when the style was created implicitly from style_reference_urls. Save it and send it as style_id next time to drop the surcharge permanently.

Rates shown are the published rates for this endpoint at the time of writing; the pricing panel on this page is authoritative.

Response Handling

Common status codes for Recraft V4 Styles Pro Vector Text to Vector Pro.

Error Responses

Validation runs before the request reaches the provider, so a 400 from this endpoint never costs you anything.

400 Bad Request — no style source

{
  "error": "Exactly one of style_id or style_reference_urls is required. Send style_id to reuse a style you already created, or style_reference_urls (1 to 10 image URLs) to build one from reference images.",
  "status": 400
}

400 Bad Request — both style sources

{
  "error": "style_id and style_reference_urls are mutually exclusive - send exactly one of them, not both.",
  "status": 400
}

400 Bad Request — missing prompt

{
  "error": "prompt is required and must be a non-empty string.",
  "status": 400
}

400 Bad Request — n out of range

{
  "error": "n must not be greater than 6 (received 7).",
  "status": 400
}

400 Bad Request — unsupported style_match value

{
  "error": "style_match must be one of: precise, flexible. \"regular\" is not supported by the Recraft V4 Styles models.",
  "status": 400
}

4xx — rejected by the provider

{
  "error": "The prompt could not be understood",
  "status": 422,
  "code": "invalid_prompt"
}

403 Insufficient Balance

"The balance is insufficient to proceed with this operation."

503 Service Unavailable — provider temporarily unavailable

{
  "error": "Image provider temporarily unavailable, please retry shortly",
  "status": 503
}

A 503 means the provider is down, rate-limited or out of capacity. It is not a problem with your request and retrying shortly is the right response.

Response Fields

Notes

The model is fixed by the endpoint you call. Any model key in your request body is dropped before the request is forwarded, so a request is always billed for the model it actually runs on. This endpoint responds synchronously — there is no queue and nothing to poll; the response carries the finished result. Output is SVG: output points to a .svg file served as image/svg+xml, which scales to any size without loss. image_format applies to raster output only and has no effect on this endpoint. Generation typically takes 20–60 seconds; larger n or larger sizes take longer.

Authentication

All requests require an API key passed via header.

Request Parameters - Text to Image

Request Headers

Response Handling

Common status codes.

Error Responses

Common error response shapes returned by the API.

400 Bad Request — Missing prompt

{
  "error": "Missing required field: prompt"
}

403 Insufficient Balance

"The balance is insufficient to proceed with this operation."

502 Bad Gateway

{
  "error": "Failed to reach upstream API",
  "status": 502
}

Response Fields

Notes

Recraft V4.1 Pro does not support the style, style_id, or negative_prompt parameters — passing any of these results in a 400 Bad Request. Image generation typically takes 30–50 seconds for single images; multiple images or higher resolutions may take longer. The output field returns a single string URL when n=1, or an array of string URLs when n>1. Generated images are in .webp format hosted on Cloudflare R2.

Authentication

All requests require an API key passed via header.

Request Parameters - Text to Image V4 - Pro

Response

// Single image (n=1, default):
{
    "output": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-0.webp"
}

// Multiple images (n>1):
{
    "output": [
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-0.webp",
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-1.webp"
    ]
}

Response Fields - Text to Image V4 - Pro

Request Headers

Response Handling

Common status codes for Text to Image V4 - Pro.

Error Responses

{
  "error": "Missing required field: prompt",
  "status": 400
}

{
  "error": "Failed to reach upstream API",
  "status": 502
}

Notes

Recraft V4 Pro does not support the style, style_id, or negative_prompt parameters. Passing any of these parameters will result in a 400 Bad Request error — they are not silently ignored. Use the exact prompt text for best results. Image generation typically takes 30–50 seconds for single images. Multiple images or higher resolutions may take longer. The output field returns a string URL when n=1, and an array of string URLs when n>1. Generated images are in .webp format. Supported image dimensions include: 2048x2048, 3072x1536, 1536x3072, 2560x1664, 1664x2560, 2432x1792, 1792x2432, 2304x1792, 1792x2304, 1664x2688, 2560x1792, 1792x2560, 2688x1536, 1536x2688, and aspect ratios: 1:1, 2:1, 1:2, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 6:10, 14:10, 10:14, 16:9, 9:16.

Authentication

All requests require an API key passed via header.

Request Parameters - Text to Image V4 - Normal

Response

// Single image (n=1, default):
{
    "output": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-0.webp"
}

// Multiple images (n>1):
{
    "output": [
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-0.webp",
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-1.webp",
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-2.webp"
    ]
}

Response Fields - Text to Image V4 - Normal

Request Headers

Response Handling

Common status codes for Text to Image V4 - Normal.

Error Responses

{
  "error": "Missing required field: prompt",
  "status": 400
}

{
  "error": "Failed to reach upstream API",
  "status": 502
}

Notes

Recraft V4 does not support the style, style_id, or negative_prompt parameters. Passing any of these parameters will result in a 400 Bad Request error — they are not silently ignored.

Image generation typically completes in 15–25 seconds. For high-resolution outputs or multiple images, processing may take slightly longer.

The output field returns a string URL when n=1, and an array of string URLs when n>1. Generated images are in .webp format.

Authentication

All requests require an API key passed via header.

Request Parameters - Image to Image V3

Content Item Types & Limits

Response

When n=1 (default) — output is a string:

{
  "output": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/winter-landscape-1773764135991-0.webp"
}

When n>1 (e.g., n=4) — output is an array:

{
  "output": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/winter-landscape-1773764135991-0.webp",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/winter-landscape-1773764135991-1.webp",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/winter-landscape-1773764135991-2.webp",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/winter-landscape-1773764135991-3.webp"
  ]
}

Response Fields - Image to Image V3

Request Headers

Response Handling

Common status codes for Image to Image V3.

Common Error Responses

{
  "error": "Missing required field: prompt",
  "status": 400
}

{
  "error": "Failed to reach upstream API",
  "status": 502
}

Notes & Tips

Usage guidelines and important details for Recraft V3 Image-to-Image API.

• Image must be under 5MB and 16MP with max 4096px on any side.
• Response time typically 15–25 seconds depending on complexity and load.
• Style presets are case-sensitive. Use exact names from the Style list in the documentation.
• Up to 6 images can be generated per request using the n parameter.
• When n=1 (default), the output field is a plain string URL. When n>1, the output field is an array of string URLs. Handle both types in your client code.
• Generated images are returned in .webp format and hosted on Cloudflare R2 storage.

Authentication

All requests require an API key passed via header.

Request Parameters - Text to Image V3

Response

// Single image (n=1, default):
{
    "output": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-0.webp"
}

// Multiple images (n>1):
{
    "output": [
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-0.webp",
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-1.webp",
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-2.webp",
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/recraft/generated-image-3.webp"
    ]
}

Response Fields - Text to Image V3

Request Headers

Response Handling

Common status codes for Text to Image V3.

Error Responses - Text to Image V3

{
  "error": "Missing required field: prompt",
  "status": 400
}

{
  "error": "Failed to reach upstream API",
  "status": 502
}

Notes & Tips - Text to Image V3

Usage considerations for Recraft V3.

• Generated images are rendered at 1MP resolution regardless of specified size.
• Style names are case-sensitive and must match exactly from the supported presets.
• Processing time is typically 10–15 seconds for single images. Multiple images or complex prompts may take slightly longer.
• Multiple images (n>1) may be generated asynchronously with slight time delays between outputs.
• The output field returns a string URL when n=1, and an array of string URLs when n>1.
• Generated images are in .webp format and hosted on Cloudflare R2.