Usage - Recraft

Dig into the details of using the Recraft API.

Generate image

Creates an image given a prompt.

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

Example

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

Output

https://img.recraft.ai/-dSeKnnWTUbG9wnzpV6OjN7I7PlFxAFmg6nyhvd3qSE/rs:fit:1024:1024:0/raw:1/plain/abs://external/images/cbb1770e-3e7e-49fd-bf17-7c689f6906c1

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
text_layout	Array of objects or null	Refer to Text Layout.	Recraft V3 only
n	integer or null, default is 1	The number of images to generate, must be between 1 and 6.	All models
style_id	UUID or null	Use a style as visual reference, refer to Styles.	Described in Styles
style	string or null	The style of the generated images, refer to Styles.	Described in Styles
model	string or null, default is `recraftv3`	The model to use for image generation.	Must be one of: `recraftv2`, `recraftv3`
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
size	string or null, default is `1024x1024`	The size of the generated images in `WxH` or `w:h` format.	Depends on model, supported values are published in Appendix
negative_prompt	string or null	A text description of undesired elements on an image.	Recraft V2 / V3
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.	All models

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': 'realistic_image'},
    files={'file1': open('image.png', 'rb')},
)
print(response['id'])

Output

{"id": "229b2a75-05e4-4580-85f9-b47ee521a00d"}

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: `realistic_image`, `digital_illustration`, `vector_illustration`, `icon`
files (required)	files	Images in PNG, JPG, or WEBP format for use as style references. The max number of images is 5. Total size of all images is limited to 5 MB.

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 model only.

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'])

Output

https://img.recraft.ai/f1LAVICjQjTDUbVlwlA4AbE_JBjEQU2t6ho6YhI0J8M/rs:fit:1024:1024:0/raw:1/plain/abs://external/images/6d85db5d-912f-4711-957c-15cbebc8cb24

Parameters

Parameter	Type	Description	Compatibility
image (required)	file	An image to modify, must be less than 5 MB in size, have resolution less than 16 MP, and max dimension less than 4096 pixels.
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.
style_id	UUID or null	Use a style as visual reference, refer to Styles.	Recraft V3 styles only
style	string or null	The style of the generated images, refer to Styles.	Recraft V3 styles only
model	string or null, default is `recraftv3`	The model to use for image generation.	Recraft V3 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.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.
text_layout	Array of objects or null	Refer to Text Layout.

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 model 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'])

Output

https://img.recraft.ai/HMd15RTSXeRfEluSPq828pZ7DW9NaI4oR2adSVk_wXc/rs:fit:1024:1024:0/raw:1/plain/abs://external/images/a97b9cc2-4498-41d8-9904-1d58e04b239b

Parameters

Body of a request should contain an image file and a mask in PNG, JPG or WEBP format and parameters passed as content type 'multipart/form-data'. The image must be no more than 5 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	Compatibility
image (required)	file	An image to modify, must be less than 5 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.
style_id	UUID or null	Use a style as visual reference, refer to Styles.	Recraft V3 styles only
style	string or null	The style of the generated images, refer to Styles.	Recraft V3 styles only
model	string or null, default is `recraftv3`	The model to use for image generation.	Recraft V3 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.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.
text_layout	Array of objects or null	Refer to Text Layout.

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 model 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'])

Output

https://img.recraft.ai/59eRxsKN87Tr-LLFleTm01RZSsSTuoZcHTzT9b1r_XM/rs:fit:1024:1024:0/raw:1/plain/abs://external/images/234453e8-6abf-472f-9ac7-9b8c7eca2f80

Parameters

Body of a request should contain an image file in PNG, JPG or WEBP format and parameters passed as content type 'multipart/form-data'. The image must be no more than 5 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	Compatibility
image (required)	file	An image to modify, must be less than 5 MB in size, have resolution less than 16 MP, and max dimension less than 4096 pixels.
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.
style_id	UUID or null	Use a style as visual reference, refer to Styles.	Recraft V3 styles only
style	string or null	The style of the generated images, refer to Styles.	Recraft V3 styles only
model	string or null, default is `recraftv3`	The model to use for image generation.	Recraft V3 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.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.
text_layout	Array of objects or null	Refer to Text Layout.

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 model 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'])

Output

https://img.recraft.ai/59eRxsKN87Tr-LLFleTm01RZSsSTuoZcHTzT9b1r_XM/rs:fit:1024:1024:0/raw:1/plain/abs://external/images/234453e8-6abf-472f-9ac7-9b8c7eca2f80

Parameters

Body of a request should contain an image file and a mask file, both in PNG, JPG or WEBP format, and parameters passed as content type 'multipart/form-data'. The image must be no more than 5 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	Compatibility
image (required)	file	An image to modify, must be less than 5 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.
style_id	UUID or null	Use a style as visual reference, refer to Styles.	Recraft V3 styles only
style	string or null	The style of the generated images, refer to Styles.	Recraft V3 styles only
model	string or null, default is `recraftv3`	The model to use for image generation.	Recraft V3 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.
controls	object or null	A set of custom parameters to tweak generation process, refer to Controls.
text_layout	Array of objects or null	Refer to Text Layout.

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'])

Output

https://img.recraft.ai/fZm6nwEjI9Qy94LukIKbxRm4w2i5crwqu459qKg7ZWY/rs:fit:1341:1341:0/raw:1/plain/abs://external/images/2835e19f-282b-419b-b80c-9231a3d51517

Parameters

Body of a request should be a file in PNG, JPG or WEBP format and parameters passed as content type 'multipart/form-data'. The image must be no more than 5 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 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'])

Output

https://img.recraft.ai/EYOLjpky-2-uClelfP61kzK-SEpIhKgLfjLFFGxmM_U/rs:fit:0:0:0/raw:1/plain/abs://external/images/e2d0cba6-12df-4141-aa21-43bfd5889990

Parameters

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'])

Output

https://img.recraft.ai/LtCo_bs3chC8zhrku0CWLpCBKv4iOODprEdeD_MY1dw/rs:fit:1760:2348:0/raw:1/plain/abs://external/images/f7d01b15-0eba-4439-a5fb-38af38fb524e

Request body

Body of a request should be a file in PNG, JPG or WEBP format and parameters passed as content type multipart/form-data. The image must be no more than 5 MB in size, have resolution no more than 4 MP, max dimension no more than 4096 pixels and min dimension no less than 32 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`.

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'])

Output

https://img.recraft.ai/DV4d9pMeq5lIluqS7m8qHyg-mb6hf5uCqEPPC8t8wy4/rs:fit:4740:3536:0/raw:1/plain/abs://external/images/fb576169-8a66-4270-a566-35713ad72020

Request body

Body of a request should be a file in PNG, JPG or WEBP format and parameters passed as content type multipart/form-data. The image must be no more than 5 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`.

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'])

Output

https://img.recraft.ai/LtCo_bs3chC8zhrku0CWLpCBKv4iOODprEdeD_MY1dw/rs:fit:1760:2348:0/raw:1/plain/abs://external/images/f7d01b15-0eba-4439-a5fb-38af38fb524e

Request body

Body of a request should contain a file and a mask, both in PNG, JPG or WEBP format, and parameters passed as content type multipart/form-data. The images must be no more than 5 MB in size, have resolution no more than 4 MP, max dimension no more than 4096 pixels and min dimension no less than 32 pixels. The mask and image must have the same dimensions.

Parameter	Type	Description
image (required)	file	An image to modify, must be less than 5 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 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`).
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`.

Variate image

Variate generates new versions of an image while keeping the overall concept intact. Each variation introduces slight differences in elements like character appearance, object position, or scene composition. The Variate 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'])

Output

https://img.recraft.ai/LtCo_bs3chC8zhrku0CWLpCBKv4iOODprEdeD_MY1dw/rs:fit:1760:2348:0/raw:1/plain/abs://external/images/f7d01b15-0eba-4439-a5fb-38af38fb524e

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": "[email protected]",
    "id": "c18a1988-45e7-4c00-82c4-4ad7d3dbce3a",
    "name": "Recraft Test"
}

Auxiliary

Styles

Styles define the visual appearance and aesthetic of generated images, including textures, visual effects, colors, composition, and overall artistic feel. Recraft offers both predefined curated styles and the ability to create custom styles. For detailed visual examples, refer to Getting Started: Styles. The style parameter accepts the name of any curated style provided by Recraft. Examples include but not limited to:

Recraft V3: Recraft V3 Raw, Photorealism, Illustration, Vector art, Enterprise, Hand-drawn, Line art, Punk Graphic, etc
Recraft V2: Photorealism, Illustration, Vector art, 3D render, Kawaii, Icon, Doodle, etc

For the complete list of available styles organized by model and category, see the Appendix: List of Styles. Some styles with identical names exist across multiple models (e.g., Photorealism is available in Recraft V2, and Recraft V3 models). Use the model parameter to explicitly specify which model version to use. The style_id parameter accepts:

style IDs created via the API;
style IDs from the Recraft web platform, accessible if :
- you own the style;
- the style is publicly available;
- the style was explicitly shared to your account.

To obtain a style ID from the web platform, open any style in the Styles panel and click the three-dot menu to copy the style ID. The style and style_id parameters cannot be used together. Specify one or the other, not both. If neither parameter is provided, the default style for the selected model will be used:

Recraft V3: Recraft V3 Raw;
Recraft V2: Photorealism.

Model compatibility:

custom styles created on the web platform are compatible with the model specified during creation;
custom styles created via the API are compatible with Recraft V3 and Recraft V3 models only.

Controls

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

Parameter	Type	Description
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]`.
colors	array of color definitions	An array of preferable colors.
background_color	color definition	Use the given color as a desired background color.
no_text	bool	Do not embed text layouts.

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.

Example

response = client.images.generate(
    prompt='race car on a track',
    style='Photorealism',
    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).

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)

Parameters

The request body must be a file in PNG, JPG, or WEBP format, submitted with the content type ‘multipart/form-data’. The image must not exceed 5 MB in size, with a maximum resolution of 16 MP, a maximum dimension of 4096 px, and a minimum dimension of 256 px.

Parameter	Type	Description
image (required)	file	The input image in PNG, WEBP or JPEG format.
image_format	string or null	Format of the output image. Supported values: png, webp.
size (required)	string	The size of the generated images in `WxH` or `w:h` format, supported values are published in Appendix.
random_seed	string or null	Optional random seed for reproducibility.
n	integer or null, default is 1	Number of variations to generate [1–6].
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`.

API

​Generate image

​Example

​Output

​Parameters

​Create style

​Example

​Output

​Request body

​Image to image

​Example

​Output

​Parameters

​Image inpainting

​Example

​Output

​Parameters

​Replace background

​Example

​Output

​Parameters

​Generate background

​Example

​Output

​Parameters

​Vectorize image

​Example

​Output

​Parameters

​Remove background

​Example

​Output

​Parameters

​Crisp upscale

​Example

​Output

​Request body

​Creative upscale

​Example

​Output

​Request body

​Erase region

​Example

​Output

​Request body

​Variate image

​Example

​Output

​Get user information

​Example

​Output

​Auxiliary

​Styles

​Controls

​Colors

​Text Layout

​Parameters

Generate image

Example

Output

Parameters

Create style

Example

Output

Request body

Image to image

Example

Output

Parameters

Image inpainting

Example

Output

Parameters

Replace background

Example

Output

Parameters

Generate background

Example

Output

Parameters

Vectorize image

Example

Output

Parameters

Remove background

Example

Output

Parameters

Crisp upscale

Example

Output

Request body

Creative upscale

Example

Output

Request body

Erase region

Example

Output

Request body

Variate image

Example

Output

Get user information

Example

Output

Auxiliary

Styles

Controls

Colors

Text Layout

Parameters