Endpoints - Recraft

Dig into the details of the Recraft API endpoints.

Authentication

We use Bearer API tokens for authentication. To access your API key, log in to Recraft and enter your profile. All requests should include your API key in an Authorization HTTP header as follows:

Authorization: Bearer RECRAFT_API_TOKEN

OpenAI Python library

Future examples will be shown using OpenAI Python library, for example, once installed, you can use the following code to be authenticated:

from openai import OpenAI

client = OpenAI(
    base_url='https://external.api.recraft.ai/v1',
    api_key=<RECRAFT_API_TOKEN>,
)

Since the Recraft API follows REST principles, you can interact with it using any standard HTTP client such as curl, as well as your preferred programming language or library.

Image inputs: multipart or JSON

Every endpoint that takes an image (or mask) as input accepts the request in two interchangeable formats:

multipart/form-data — upload the binary file directly using form fields (image, mask, file, …). This is convenient for local files.
application/json — pass the image by reference instead of uploading bytes. Each file field has a JSON counterpart that accepts a public URL or a data URL (a data:image/...;base64,... string).

The mapping between the multipart file fields and their JSON counterparts:

Multipart field	JSON field	Type
`image`	`image_url`	string — URL or data URL of the input image
`mask`	`mask_url`	string — URL or data URL of the mask image
`file`	`image_url`	string — URL or data URL of the input image
`files` (Create style)	`image_urls`	array of strings — URLs or data URLs of the input images

All other parameters are identical between the two formats. Use JSON when your image is already hosted somewhere (just send the URL) or when a JSON body fits your client better; use multipart to upload local files directly. The examples below show both variants where applicable.

Generate image

Creates an image given a prompt.

POST https://external.api.recraft.ai/v1/images/generations

In addition to the general endpoint above, two specialized variants accept the same request body but constrain the allowed model and style values to a single output type:

POST https://external.api.recraft.ai/v1/images/generations/raster
POST https://external.api.recraft.ai/v1/images/generations/vector

/generations/raster — only raster models (any model from the list above whose name does not end in _vector) and raster styles are accepted. Requests using a vector model or vector style are rejected.
/generations/vector — only vector models (any model from the list above whose name ends in _vector) and vector styles are accepted. Requests using a raster model or raster style are rejected.

Use these variants when you want the server to enforce the output type — for example, in an agent or workflow that must produce only raster (or only vector) images. The base /generations endpoint remains available and accepts any supported model or style.

Example

response = client.images.generate(
    prompt='race car on a track',
)
print(response.data[0].url)

Parameters

Parameter	Type	Description	Compatibility
prompt (required)	string	A text description of the desired image(s).	Maximum prompt length depends on model, refer to Appendix
n	integer or null, default is 1	The number of images to generate, must be between 1 and 6.	All models
model	string or null, default is `recraftv4_1`	The model to use for image generation.	Must be one of: `recraftv4_1` `recraftv4_1_vector` `recraftv4_1_pro` `recraftv4_1_pro_vector` `recraftv4_1_utility` `recraftv4_1_utility_vector` `recraftv4_1_utility_pro` `recraftv4_1_utility_pro_vector` `recraftv4` `recraftv4_vector` `recraftv4_pro` `recraftv4_pro_vector` `recraftv3` `recraftv3_vector` `recraftv2` `recraftv2_vector`
style	string or null	The style of the generated images, refer to Styles.	V2 / V3 styles
style_id	UUID or null	Use a style as visual reference, refer to Styles.	V2 / V3 styles
size	string or null	The size of the generated images in `WxH` or `w:h` format. If not specified, the size is auto-selected based on the prompt.	Depends on model, supported values are published in Appendix
negative_prompt	string or null	A text description of undesired elements on an image.	V2 / V3 models
random_seed	integer or null	Seed for reproducible generation.	All models
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.	All models
text_layout	Array of objects or null	Refer to Text Layout.	V3 models only
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.	All models, partially supported for V4

Hint: if OpenAI Python Library is used, non-standard parameters can be passed using the extra_body argument. For example:

response = client.images.generate(
    prompt='race car on a track',
    extra_body={
        'style_id': style_id,
        'controls': {
            ...
        }
    }
)
print(response.data[0].url)

Create style

Upload a set of images to create a style reference.

POST https://external.api.recraft.ai/v1/styles

Example

response = client.post(
    path='/styles',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    body={'style': 'digital_illustration'},
    files={'file1': open('image.png', 'rb')},
)
print(response['id'])

response = client.post(
    path='/styles',
    cast_to=object,
    body={
        'style': 'digital_illustration',
        'image_urls': ['https://example.com/image.png'],
    },
)
print(response['id'])

Output

{
    "id": "229b2a75-05e4-4580-85f9-b47ee521a00d",
    "style": "digital_illustration",
    "creation_time": "2024-01-01T00:00:00Z",
    "is_private": true,
    "credits": 40
}

Request body

Upload a set of images to create a style reference.

Parameter	Type	Description
style (required)	string	The base style of the generated images, should be one of: `any`, `realistic_image`, `digital_illustration`, `vector_illustration`, `icon`, `logo_raster`
files	files	(multipart only) Images in PNG, JPG, or WEBP format for use as style references, sent as multipart file parts (any field name). The max number of images is 5. Total size of all images is limited to 5 MB (each file must also be under the 10 MB upload limit). Required unless `source_styles` is provided.
image_urls	array of strings	(JSON only) URLs or data URLs of the reference images, the JSON-body counterpart of `files`. Same image format, count, and size limits apply. Required unless `source_styles` is provided.
model	string or null	The transform model the style is created for, e.g. `recraftv3`, `recraftv3_vector`.
image_weights	array of numbers or null	Per-image weights; the number of weights must match the number of uploaded images.
source_styles	array of UUIDs or null	Existing style IDs to mix into the new style. May be used instead of, or together with, uploaded images.
source_style_weights	array of numbers or null	Per-source-style weights; the number of weights must match the number of `source_styles`.
prompt	string or null	Optional text prompt associated with the style.
mix_policy	string or null	How sources are mixed when combining images/source styles. Must be one of `PaletteMatch`, `MaxWeight`.

Image to image

Image-to-image operation tool allows you to create images similar to a given image, preserving certain aspects like composition, color, or subject identity while altering others based on the prompt. This can be used to create variations of the image or images that have similar composition to existing image. Use prompt to describe the new image and strength to define similarity level. Note: This operation is available with Recraft V3 and Recraft V4 models (raster and vector).

POST https://external.api.recraft.ai/v1/images/imageToImage

Example

response = client.post(
    path='/images/imageToImage',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={
        'image': open('image.png', 'rb'),
    },
    body={
        'prompt': 'winter',
        'strength': 0.2,
    },
)
print(response['data'][0]['url'])

response = client.post(
    path='/images/imageToImage',
    cast_to=object,
    body={
        'image_url': 'https://example.com/image.png',
        'prompt': 'winter',
        'strength': 0.2,
    },
)
print(response['data'][0]['url'])

Parameters

In JSON mode, replace the image file with image_url (a URL or data URL of the input image); all other parameters are the same.

Parameter	Type	Description	Compatibility
image (required)	file	(multipart) An image to modify, must be less than 10 MB in size, have resolution less than 16 MP, and max dimension less than 4096 pixels. PNG, JPG, WEBP, or SVG. The output format is determined by the selected model.
image_url (required)	string	(JSON) URL or data URL of the input image, the JSON-body counterpart of `image`. Same format and size limits apply.
prompt (required)	string	A text description of areas to change.	refer to Appendix
strength (required)	float	Defines the difference with the original image, should lie in `[0, 1]`, where `0` means almost identical, and `1` means minimal similarity.
n	integer or null, default is 1	The number of images to generate, must be between 1 and 6.
model	string or null, default is `recraftv4_1`	The model to use for image generation.	Must be one of the Recraft V3 / V4 models: `recraftv3`, `recraftv3_vector`, `recraftv4`, `recraftv4_vector`, `recraftv4_pro`, `recraftv4_pro_vector`, `recraftv4_1`, `recraftv4_1_vector`, `recraftv4_1_pro`, `recraftv4_1_pro_vector`, `recraftv4_1_utility`, `recraftv4_1_utility_vector`, `recraftv4_1_utility_pro`, `recraftv4_1_utility_pro_vector`
style	string or null	The style of the generated images, refer to Styles.	V3 / V4 styles
style_id	UUID or null	Use a style as visual reference, refer to Styles.	V3 / V4 styles
random_seed	integer or null	Seed for reproducible generation.
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.
negative_prompt	string or null	A text description of undesired elements on an image.
text_layout	Array of objects or null	Refer to Text Layout.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.

Image inpainting

Inpainting lets you regenerate specific parts of an image while keeping the rest intact. This is useful for correcting details, replacing elements, or making creative changes without starting from scratch. It uses a mask to identify the areas to be filled in, where white pixels represent the regions to inpaint, and black pixels indicate the areas to keep intact, i.e. the white pixels are filled based on the input provided in the prompt. Note: This operation is available with Recraft V3, Recraft V3 Vector models only.

POST https://external.api.recraft.ai/v1/images/inpaint

Example

response = client.post(
    path='/images/inpaint',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={
        'image': open('image.png', 'rb'),
        'mask': open('mask.png', 'rb'),
    },
    body={
        'prompt': 'winter',
    },
)
print(response['data'][0]['url'])

response = client.post(
    path='/images/inpaint',
    cast_to=object,
    body={
        'image_url': 'https://example.com/image.png',
        'mask_url': 'https://example.com/mask.png',
        'prompt': 'winter',
    },
)
print(response['data'][0]['url'])

Parameters

The request can be sent either as multipart/form-data (uploading the image and mask files) or as application/json (passing image_url and mask_url instead). The image must be in PNG, JPG, WEBP, or SVG format and the mask in PNG, JPG, or WEBP. The image must be no more than 10 MB in size, have resolution no more than 16 MP, max dimension no more than 4096 pixels and min dimension no less than 256 pixels. The output format (raster or vector) is determined by the selected model.

Parameter	Type	Description	Compatibility
image (required)	file	An image to modify, must be less than 10 MB in size, have resolution less than 16 MP, and max dimension less than 4096 pixels.
mask (required)	file	An image encoded in grayscale color mode, used to define the specific regions of an image that need modification. The white pixels represent the parts of the image that will be inpainted, while black pixels indicate the parts of the image that will remain unchanged. Should have exactly the same size as the image. Each pixel of the image should be either pure black (value `0`) or pure white (value `255`).
prompt (required)	string	A text description of areas to change.	refer to Appendix
n	integer or null, default is 1	The number of images to generate, must be between 1 and 6.
model	string or null, default is `recraftv3`	The model to use for image generation.	Must be one of: `recraftv3`, `recraftv3_vector`
style	string or null	The style of the generated images, refer to Styles.	V3 styles only
style_id	UUID or null	Use a style as visual reference, refer to Styles.	V3 styles only
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.
negative_prompt	string or null	A text description of undesired elements on an image.
text_layout	Array of objects or null	Refer to Text Layout.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.

Image outpainting

Outpainting extends an image beyond its original boundaries by generating new content around it. This is useful for changing the aspect ratio, adding scenery, or zooming out to reveal more of the scene while keeping the original image intact. The area to be generated can be specified either by per-side pixel margins via expand_left, expand_right, expand_top, expand_bottom (which extend the image by the given amount on each side), or by a target size (which places the source image inside the resulting image of the given dimensions); these two options cannot be used together. After that, it is also possible to specify zoom_out_percentage, which scales the source image down relative to the resulting image by the given percentage and can be combined with either option or used on its own. At least one of size, expand_*, or zoom_out_percentage must be specified. Note: This operation is available with Recraft V3, Recraft V3 Vector models only.

POST https://external.api.recraft.ai/v1/images/outpaint

Example

response = client.post(
    path='/images/outpaint',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={
        'image': open('image.png', 'rb'),
    },
    body={
        'prompt': 'a mountain landscape',
        'size': '16:9',
        'zoom_out_percentage': 25.0,
    },
)
print(response['data'][0]['url'])

response = client.post(
    path='/images/outpaint',
    cast_to=object,
    body={
        'image_url': 'https://example.com/image.png',
        'prompt': 'a mountain landscape',
        'size': '16:9',
        'zoom_out_percentage': 25.0,
    },
)
print(response['data'][0]['url'])

Parameters

The request can be sent either as multipart/form-data (uploading the image file) or as application/json (passing image_url — a URL or data URL — instead). The input image must be in PNG, JPG, WEBP, or SVG format. The image must be no more than 10 MB in size, have resolution no more than 16 MP, max dimension no more than 4096 pixels and min dimension no less than 256 pixels. The resulting image dimensions (after applying expand_*) must not exceed 4096 pixels on either side. The output format (raster or vector) is determined by the selected model.

Parameter	Type	Description	Compatibility
image (required)	file	An image to extend, must be less than 10 MB in size, have resolution less than 16 MP, and max dimension less than 4096 pixels.
prompt (required)	string	A text description of the content to generate in the extended area.	refer to Appendix
expand_left	integer or null	Number of pixels to add to the left side of the image, must be in range `[0, 4096]`. Cannot be combined with `size`.
expand_right	integer or null	Number of pixels to add to the right side of the image, must be in range `[0, 4096]`. Cannot be combined with `size`.
expand_top	integer or null	Number of pixels to add to the top side of the image, must be in range `[0, 4096]`. Cannot be combined with `size`.
expand_bottom	integer or null	Number of pixels to add to the bottom side of the image, must be in range `[0, 4096]`. Cannot be combined with `size`.
size	string or null	The size of the resulting outpainted image in `WxH` or `w:h` format. The source image is placed inside the resulting image. Cannot be combined with `expand_*`.	Depends on model, supported values are published in Appendix
zoom_out_percentage	float or null, default is `0`	Percentage by which the source image is scaled down before outpainting, must be in range `[0, 100)`. Higher values produce more surrounding context. Can be used on its own or combined with `size` or `expand_*`.
n	integer or null, default is 1	The number of images to generate, must be between 1 and 6.
model	string or null, default is `recraftv3`	The model to use for image generation.	Must be one of: `recraftv3`, `recraftv3_vector`
style	string or null	The style of the content generated in the extended area, refer to Styles.	V3 styles only
style_id	UUID or null	Use a style as visual reference for the content generated in the extended area, refer to Styles.	V3 styles only
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.
negative_prompt	string or null	A text description of undesired elements on an image.
text_layout	Array of objects or null	Refer to Text Layout.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.

Replace background

Replace Background operation detects background of an image and modifies it according to given prompt. Note: This operation is available with Recraft V3, Recraft V3 Vector models only.

POST https://external.api.recraft.ai/v1/images/replaceBackground

Example

response = client.post(
    path='/images/replaceBackground',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={
        'image': open('image.png', 'rb'),
    },
    body={
        'prompt': 'winter',
    },
)
print(response['data'][0]['url'])

response = client.post(
    path='/images/replaceBackground',
    cast_to=object,
    body={
        'image_url': 'https://example.com/image.png',
        'prompt': 'winter',
    },
)
print(response['data'][0]['url'])

Parameters

The request can be sent either as multipart/form-data (uploading the image file) or as application/json (passing image_url — a URL or data URL — instead). The input image must be in PNG, JPG, WEBP, or SVG format. The image must be no more than 10 MB in size, have resolution no more than 16 MP, max dimension no more than 4096 pixels and min dimension no less than 256 pixels. The output format (raster or vector) is determined by the selected model.

Parameter	Type	Description	Compatibility
image (required)	file	(multipart) An image to modify, must be less than 10 MB in size, have resolution less than 16 MP, and max dimension less than 4096 pixels.
image_url (required)	string	(JSON) URL or data URL of the input image, the JSON-body counterpart of `image`.
prompt (required)	string	A text description of areas to change.	refer to Appendix
n	integer or null, default is 1	The number of images to generate, must be between 1 and 6.
model	string or null, default is `recraftv3`	The model to use for image generation.	Must be one of: `recraftv3`, `recraftv3_vector`
style	string or null	The style of the generated images, refer to Styles.	V3 styles only
style_id	UUID or null	Use a style as visual reference, refer to Styles.	V3 styles only
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.
negative_prompt	string or null	A text description of undesired elements on an image.
text_layout	Array of objects or null	Refer to Text Layout.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.

Generate background

Generate Background operation generates a background for a given image, based on a prompt and a mask that specifies the regions to fill. Note: This operation is available with Recraft V3, Recraft V3 Vector models only.

POST https://external.api.recraft.ai/v1/images/generateBackground

Example

response = client.post(
    path='/images/generateBackground',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={
        'image': open('image.png', 'rb'),
        'mask': open('mask.png', 'rb'),
    },
    body={
        'prompt': 'winter',
    },
)
print(response['data'][0]['url'])

response = client.post(
    path='/images/generateBackground',
    cast_to=object,
    body={
        'image_url': 'https://example.com/image.png',
        'mask_url': 'https://example.com/mask.png',
        'prompt': 'winter',
    },
)
print(response['data'][0]['url'])

Parameters

Parameter	Type	Description	Compatibility
image (required)	file	An image to modify, must be less than 10 MB in size, have resolution less than 16 MP, and max dimension less than 4096 pixels.
mask (required)	file	An image encoded in grayscale color mode, used to define the specific regions of an image that need modification. The white pixels represent the parts of the image that will be inpainted, while black pixels indicate the parts of the image that will remain unchanged. Should have exactly the same size as the image. Each pixel of the image should be either pure black (value `0`) or pure white (value `255`).
prompt (required)	string	A text description of areas to change.	refer to Appendix
n	integer or null, default is 1	The number of images to generate, must be between 1 and 6.
model	string or null, default is `recraftv3`	The model to use for image generation.	Must be one of: `recraftv3`, `recraftv3_vector`
style	string or null	The style of the generated images, refer to Styles.	V3 styles only
style_id	UUID or null	Use a style as visual reference, refer to Styles.	V3 styles only
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.
negative_prompt	string or null	A text description of undesired elements on an image.
text_layout	Array of objects or null	Refer to Text Layout.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.

Vectorize image

Converts a given raster image to SVG format.

POST https://external.api.recraft.ai/v1/images/vectorize

Example

response = client.post(
    path='/images/vectorize',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])

response = client.post(
    path='/images/vectorize',
    cast_to=object,
    body={'image_url': 'https://example.com/image.png'},
)
print(response['image']['url'])

Parameters

The request can be sent either as multipart/form-data (uploading the image as the file field) or as application/json (passing image_url — a URL or data URL — instead). The input image must be in PNG, JPG, or WEBP format. The image must be no more than 10 MB in size, have resolution no more than 16 MP, max dimension no more than 4096 pixels and min dimension no less than 256 pixels.

Parameter	Type	Description
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.

Remove background

Removes background of a given image. Accepts raster (PNG, JPG, WEBP) or SVG input. When the input is an SVG, the result is returned as an SVG (vector output); raster input returns a raster image.

POST https://external.api.recraft.ai/v1/images/removeBackground

Example

response = client.post(
    path='/images/removeBackground',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])

response = client.post(
    path='/images/removeBackground',
    cast_to=object,
    body={'image_url': 'https://example.com/image.png'},
)
print(response['image']['url'])

Parameters

The request can be sent either as multipart/form-data (uploading the image as the file field) or as application/json (passing image_url — a URL or data URL — instead). The input image must be in PNG, JPG, WEBP, or SVG format. The image must be no more than 10 MB in size, have resolution no more than 16 MP, max dimension no more than 4096 pixels and min dimension no less than 256 pixels. SVG inputs smaller than the 256 px minimum are scaled up before processing; SVGs exceeding the max dimension/resolution, and unsafe SVGs, are rejected.

Parameter	Type	Description
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.

Crisp upscale

Enhances a given raster image using ‘crisp upscale’ tool, increasing image resolution, making the image sharper and cleaner.

POST https://external.api.recraft.ai/v1/images/crispUpscale

Example

response = client.post(
    path='/images/crispUpscale',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])

response = client.post(
    path='/images/crispUpscale',
    cast_to=object,
    body={'image_url': 'https://example.com/image.png'},
)
print(response['image']['url'])

Request body

Parameter	Type	Description
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.

Creative upscale

Enhances a given raster image using ‘creative upscale’ tool, boosting resolution with a focus on refining small details and faces.

POST https://external.api.recraft.ai/v1/images/creativeUpscale

Example

response = client.post(
    path='/images/creativeUpscale',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])

response = client.post(
    path='/images/creativeUpscale',
    cast_to=object,
    body={'image_url': 'https://example.com/image.png'},
)
print(response['image']['url'])

Request body

Parameter	Type	Description
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.

Erase region

Erases a region of a given raster image following a given mask, where white pixels represent the regions to erase, and black pixels indicate the areas to keep intact.

POST https://external.api.recraft.ai/v1/images/eraseRegion

Example

response = client.post(
    path='/images/eraseRegion',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={'image': open('image.png', 'rb'), 'mask': open('mask.png', 'rb')},
)
print(response['image']['url'])

response = client.post(
    path='/images/eraseRegion',
    cast_to=object,
    body={
        'image_url': 'https://example.com/image.png',
        'mask_url': 'https://example.com/mask.png',
    },
)
print(response['image']['url'])

Request body

The request can be sent either as multipart/form-data (uploading the image and mask files) or as application/json (passing image_url and mask_url instead). The image must be in PNG, JPG, WEBP, or SVG format and the mask in PNG, JPG, or WEBP. The images must be no more than 10 MB in size, have resolution no more than 16 MP, max dimension no more than 4096 pixels and min dimension no less than 256 pixels. The mask and image must have the same dimensions. When the input is an SVG, the result is returned as an SVG; a raster input returns a raster image.

Parameter	Type	Description
image (required)	file	(multipart) An image to modify, must be less than 10 MB in size, have resolution less than 16 MP, and max dimension less than 4096 pixels.
image_url (required)	string	(JSON) URL or data URL of the input image, the JSON-body counterpart of `image`.
mask (required)	file	(multipart) An image encoded in grayscale color mode, used to define the specific regions of the image to be erased. The white pixels represent the parts of the image that will be erased, while black pixels indicate the parts of the image that will remain unchanged. Should have exactly the same size as the image. Each pixel of the image should be either pure black (value `0`) or pure white (value `255`).
mask_url (required)	string	(JSON) URL or data URL of the mask image, the JSON-body counterpart of `mask`.
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.

Remix image

Remix generates new versions of an image while keeping the overall concept intact. Each remix introduces slight differences in elements like character appearance, object position, or scene composition. The Remix function does not use a prompt. Instead, it uses the visual content of the original image to generate alternatives in different aspect ratios.


POST https://external.api.recraft.ai/v1/images/variateImage

Example

response = client.post(
    path='/images/variateImage',
    cast_to=object,
    options={'headers': {'Content-Type': 'multipart/form-data'}},
    files={'image': open('image.png', 'rb')},
    body={'size': '1024x1024'}
)
print(response['data'][0]['url'])

response = client.post(
    path='/images/variateImage',
    cast_to=object,
    body={
        'image_url': 'https://example.com/image.png',
        'size': '1024x1024',
    },
)
print(response['data'][0]['url'])

Parameters

The request can be sent either as multipart/form-data (uploading the image file) or as application/json (passing image_url — a URL or data URL — instead). The input image must be in PNG, JPG, WEBP, or SVG format. The image must not exceed 10 MB in size, with a maximum resolution of 16 MP, a maximum dimension of 4096 px, and a minimum dimension of 256 px. The output format (raster or vector) is determined by the selected model.

Parameter	Type	Description
image (required)	file	(multipart) The input image in PNG, WEBP, JPEG, or SVG format.
image_url (required)	string	(JSON) URL or data URL of the input image, the JSON-body counterpart of `image`.
size (required)	string	The size of the generated images in `WxH` or `w:h` format, supported values are published in Appendix.
n	integer or null, default is 1	Number of variations to generate [1–6].
model	string or null	The model to use for generation. The output format (raster or vector) is determined by the selected model.
random_seed	integer or null	Optional random seed for reproducibility.
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.

Explore

Generates a set of images based on a prompt, designed for visual exploration and discovery of diverse results.

POST https://external.api.recraft.ai/v1/images/explore

Example

response = client.post(
    path='/images/explore',
    cast_to=object,
    body={
        'prompt': 'race car on a track',
    },
)
print(response['data'][0]['url'])

Parameters

Parameter	Type	Description
prompt (required)	string	A text description of the desired image(s). Maximum prompt length depends on model, refer to Appendix.
model	string or null, default is `recraftv4_1`	The model to use for image generation. Must be one of: `recraftv4_1`, `recraftv4_1_vector`, `recraftv4_1_pro`, `recraftv4_1_pro_vector`, `recraftv4`, `recraftv4_vector`, `recraftv4_pro`, `recraftv4_pro_vector`.
style	string or null	The style of the generated images, refer to Styles.
style_id	UUID or null	Use a style as visual reference, refer to Styles.
size	string or null, default is `1:1`	The size of the generated images in `WxH` or `w:h` format. Depends on model, supported values are published in Appendix.
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls. Supports `prompt_to_image` controls.

Explore similar

Start from an image you already created and generate new images that are visually similar to the given source image. The source image must be one previously generated via the Explore endpoint. The similarity parameter controls how closely the results should resemble the source.

POST https://external.api.recraft.ai/v1/images/explore/similar

Example

response = client.post(
    path='/images/explore/similar',
    cast_to=object,
    body={
        'source_image_id': 'c18a1988-45e7-4c00-82c4-4ad7d3dbce3a',
        'similarity': 5,
    },
)
print(response['data'][0]['url'])

Parameters

Parameter	Type	Description
source_image_id (required)	UUID	The ID of the source image to use as a visual reference for exploration.
similarity (required)	integer	Defines how closely the generated images should resemble the source image. The value should be between `1` and `5`: `1` — a little bit similar, `2` — moderately similar, `3` — quite similar, `4` — very similar, `5` — extremely similar.
response_format	string or null, default is `url`	The format in which the generated images are returned. Must be one of `url` or `b64_json`.

Enhance prompt

Expands a short prompt into a richer, more detailed description with added visual context, style cues, and composition details. Use the enhanced prompt in any image generation endpoint to produce more vivid and accurate results.

POST https://external.api.recraft.ai/v1/prompts/enhance

Example

response = client.post(
    path='/prompts/enhance',
    cast_to=object,
    body={'prompt': 'race car on a track'},
)
print(response['enhanced_prompt'])

Parameters

Parameter	Type	Description
prompt (required)	string	The original prompt to enhance. Must not be empty and must not exceed `2000` characters.

Get user information

Returns information of the current user including credits balance.

GET https://external.api.recraft.ai/v1/users/me

Example

response = client.get(path='/users/me', cast_to=object)
print(response)

Output

{
    "credits": 1000,
    "email": "test@example.com",
    "id": "c18a1988-45e7-4c00-82c4-4ad7d3dbce3a",
    "name": "Recraft Test"
}

Auxiliary

Controls

The generation process can be adjusted with a number of tweaks.

Parameter	Type	Description	Compatibility
colors	array of color definitions	An array of preferable colors.	All models
background_color	color definition	Use the given color as a desired background color.	All models
artistic_level	integer or null	Defines the artistic tone of your image. At a simple level, the person looks straight at the camera in a static and clean style. Dynamic and eccentric levels introduce movement and creativity. The value should be in the range `[0..5]`.	V3 models only
no_text	bool	Do not embed text layouts.	V3 models only

Colors

Color type is defined as an object with the following fields

Parameter	Description
rgb (required)	An array of 3 integer values in range of `0...255` defining RGB color model.
weight	An optional number in range `0.0...1.0` indicating the relative preference of this color. The sum of weights across all `colors` must not exceed `1.0`.

Example

response = client.images.generate(
    prompt='race car on a track',
    extra_body={
        'controls': {
            'colors': [
                {'rgb': [0, 255, 0]}
            ]
        }
    }
)
print(response.data[0].url)

Text Layout

Text layout is used to define spatial and textual attributes for individual text elements. Each text element consists of an individual word and its bounding box (bbox). This feature is supported by Recraft V3 and Recraft V3 Vector models only.

Parameter	Description
text (required)	A single word containing only supported characters.
bbox (required)	A bounding box representing a 4-angled polygon. Each point in the polygon is defined by relative coordinates.

Bounding box: The bounding box (bbox) is a list of 4 points representing a 4-angled figure (not necessarily a rectangle). Each point specifies its coordinates relative to the layout dimensions, where (0, 0) is the top-left corner, (1, 1) is the bottom-right corner. Coordinates: Coordinates are relative to the layout dimensions. Coordinates can extend beyond the [0, 1] range, such values indicate that the shape will be cropped. Points: The bounding box must always have exactly 4 points. Each point is an array of two floats [x, y] representing the relative position. Supported characters The text field must contain a single word composed only of the following characters:

! " # $ % & ' ( ) * + , - . / 
0 1 2 3 4 5 6 7 8 9 
: ; < > ? @ 
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 
_ { } 
Ø Đ Ħ Ł Ŋ Ŧ 
Α Β Ε Ζ Η Ι Κ Μ Ν Ο Ρ Τ Υ Χ 
І 
А В Е К М Н О Р С Т У Х 
ß ẞ
 

Any character not listed above will result in validation errors. Example

response = client.images.generate(
    prompt="cute red panda with a sign",
    style="Illustration",
    extra_body={
        "text_layout": [
            {
                "text": "Recraft",
                "bbox": [[0.3, 0.45], [0.6, 0.45], [0.6, 0.55], [0.3, 0.55]],
            },
            {
                "text": "AI",
                "bbox": [[0.62, 0.45], [0.70, 0.45], [0.70, 0.55], [0.62, 0.55]],
            },
        ]
    },
)
print(response.data[0].url)

​Authentication

​OpenAI Python library

​Image inputs: multipart or JSON

​Generate image

​Example

​Parameters

​Create style

​Example

​Output

​Request body

​Image to image

​Example

​Parameters

​Image inpainting

​Example

​Parameters

​Image outpainting

​Example

​Parameters

​Replace background

​Example

​Parameters

​Generate background

​Example

​Parameters

​Vectorize image

​Example

​Parameters

​Remove background

​Example

​Parameters

​Crisp upscale

​Example

​Request body

​Creative upscale

​Example

​Request body

​Erase region

​Example

​Request body

​Remix image

​Example

​Parameters

​Explore

​Example

​Parameters

​Explore similar

​Example

​Parameters

​Enhance prompt

​Example

​Parameters

​Get user information

​Example

​Output

​Auxiliary

​Controls

​Colors

​Text Layout

Authentication

OpenAI Python library

Image inputs: multipart or JSON

Generate image

Example

Parameters

Create style

Example

Output

Request body

Image to image

Example

Parameters

Image inpainting

Example

Parameters

Image outpainting

Example

Parameters

Replace background

Example

Parameters

Generate background

Example

Parameters

Vectorize image

Example

Parameters

Remove background

Example

Parameters

Crisp upscale

Example

Request body

Creative upscale

Example

Request body

Erase region

Example

Request body

Remix image

Example

Parameters

Explore

Example

Parameters

Explore similar

Example

Parameters

Enhance prompt

Example

Parameters

Get user information

Example

Output

Auxiliary

Controls

Colors

Text Layout