Learn the basics of the Recraft API, including raster and vector image generation, style creation, image generation in your brand style and colors, image vectorization and background removal.
Authenticate and interact with our API in a matter of minutes.
Understand our flexible API pricing plans.
Dig into the details of using the Recraft API.
Practical guides for both CLI and Python usage.
A style is a descriptor that defines the visual appearance and feel of generated images. This includes a wide array of elements such as textures and visual effects, shapes and colors, composition and lines, etc. There are four classes of base styles: realistic image, digital illustration, vector illustration and icon.
Images of style “realistic” are expected to look like just ordinary photographs made with a digital camera or a smartphone or a film camera.
-min.png)
-min.png)
Images of style “digital illustration” are pictures drawn by hand or using computers - virtually everything except photos and vector illustrations. The most crucial difference from “realistic images” is that illustrations possess simplified textures (like in 3D-rendered or manually drawn images) - or they are stylized in a certain creative way. The difference from “vector illustration” is that “digital illustrations” allow for more complex color transitions, shades, fine textures.
-min.png)
-min.png)
Images of style “vector illustration” are expected to look like those drawn using vector graphics (see Wikipedia). Usually, they use only a few different colors at once, shapes are filled with flat colors or simple color gradients. Shapes of objects can be arbitrarily complex.
-min.png)
-min.png)
Images of style “icon” are small digital images or symbols used in the graphical user interface. They are designed to be simple and recognizable at small sizes, often visually summarizing the action or object they stand for, or they can act as the visual identity for an app or a website and are crucial in branding.
-min.png)
-min.png)
A style can be refined by adding a substyle for more precise definition. Below, you will find a list of supported styles and corresponding substyles. Please note that the available styles and substyles may vary depending on the model. Additionally, you have an option to create your own style by combining a base style (e.g. realistic image, digital illustration, vector illustration or icon) with a collection of reference images.
Recraft developed two powerful models: Recraft 20B and Recraft V3.
The Recraft 20B model was released in February 2024 and was the first AI model built specifically for designers. It allowed them to create both vector and raster images that are anatomically perfect, maintain consistent brand style and also iterate with ultimate control and precision.
In October 2024 the new model was introduced - Recraft V3. Our team trained a new SOTA model from scratch and set a new standard for excellence in image generation. Recraft V3 participated in the Hugging Face’s industry-leading Text-to-Image Model Leaderboard by Artificial Analysis. It secured #1 place with ELO rating of 1172.
Now both models are available through the Recraft API.
The following are the API Unit packages available from Recraft for the use of the Recraft API Service. API Unit packages must be purchased in advance and all API Unit packages are non-cancellable and non-refundable. Any number of unit packages can be bought.
The following are the Service charges (in API Units) for use of the API Services. API Units will be automatically deducted from Member’s pre-purchased API Unit package upon use of the described Service by the Member. The Recraft Service is the system of record for determining API Unit usage. Please note, Services charges do not depend on model.
Authenticate and interact with our API in a matter of minutes.
We use Bearer API tokens for authentication. To access your API key, log in to Recraft, enter your profile and hit 'Generate' (available only if your API units balance is above zero). All requests should include your API key in an Authorization HTTP header as follows:
Authorization: Bearer RECRAFT_API_TOKEN
The Recraft API adheres to REST principles, allowing you to interact using any utilities (e.g., curl), programming languages, or libraries of your choice.
One of the easiest of available alternatives is OpenAI Python library which is also compatible with Recraft API, but it’s important to remember that not all parameters/options are supported or implemented. Additionally, some parameters may have different meanings, or they may be quietly ignored if they are not applicable to the Recraft API.
Future examples will be shown using that 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=<TOKEN>,
)Dig into the details of using the Recraft API.
Creates an image given a prompt.
POST https://external.api.recraft.ai/v1/images/generationsresponse = client.images.generate(
prompt='race car on a track',
style='digital_illustration',
)
print(response.data[0].url)https://img.recraft.ai/-dSeKnnWTUbG9wnzpV6OjN7I7PlFxAFmg6nyhvd3qSE/rs:fit:1024:1024:0/raw:1/plain/abs://external/images/cbb1770e-3e7e-49fd-bf17-7c689f6906c1
Note: style_id and style parameters are mutually exclusive. If neither of the two parameters is specified, the default style of realistic_image will be used
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)Inpainting replaces or modifies specific parts of an image. 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.
POST https://external.api.recraft.ai/v1/images/inpaintresponse = 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'])
https://img.recraft.ai/HMd15RTSXeRfEluSPq828pZ7DW9NaI4oR2adSVk_wXc/rs:fit:1024:1024:0/raw:1/plain/abs://external/images/a97b9cc2-4498-41d8-9904-1d58e04b239bBody of a request should contains an image file and a mask in PNG format and parameters passed as content type 'multipart/form-data'.
Note: style_id and style parameters are mutually exclusive. If neither of the two parameters is specified, the default style of "any" will be used
Replace Background operation detects background of an image and modifies it according to given prompt.
POST https://external.api.recraft.ai/v1/images/replaceBackgroundresponse = 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'])
https://img.recraft.ai/59eRxsKN87Tr-LLFleTm01RZSsSTuoZcHTzT9b1r_XM/rs:fit:1024:1024:0/raw:1/plain/abs://external/images/234453e8-6abf-472f-9ac7-9b8c7eca2f80Body of a request should contains an image file in PNG format and parameters passed as content type 'multipart/form-data'.
Note: style_id and style parameters are mutually exclusive. If neither of the two parameters is specified, the default style of "any" will be used
Converts a given raster image to SVG format.
POST https://external.api.recraft.ai/v1/images/vectorizeresponse = 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'])https://img.recraft.ai/fZm6nwEjI9Qy94LukIKbxRm4w2i5crwqu459qKg7ZWY/rs:fit:1341:1341:0/raw:1/plain/abs://external/images/2835e19f-282b-419b-b80c-9231a3d51517Body of a request should be a file in PNG format and parameters passed as content type 'multipart/form-data'.
Removes background of a given raster image.
POST https://external.api.recraft.ai/v1/images/removeBackgroundresponse = 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'])
https://img.recraft.ai/EYOLjpky-2-uClelfP61kzK-SEpIhKgLfjLFFGxmM_U/rs:fit:0:0:0/raw:1/plain/abs://external/images/e2d0cba6-12df-4141-aa21-43bfd5889990Body of a request should be a file in PNG format and parameters passed as content type 'multipart/form-data'.
Enhances a given raster image using ‘clarity upscale’ tool, increasing image resolution, making the image sharper and cleaner.
POST https://external.api.recraft.ai/v1/images/clarityUpscaleresponse = client.post(
path='/images/clarityUpscale',
cast_to=object,
options={'headers': {'Content-Type': 'multipart/form-data'}},
files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])
https://img.recraft.ai/LtCo_bs3chC8zhrku0CWLpCBKv4iOODprEdeD_MY1dw/rs:fit:1760:2348:0/raw:1/plain/abs://external/images/f7d01b15-0eba-4439-a5fb-38af38fb524eBody of a request should be a file in PNG format and parameters passed as content type multipart/form-data.
Enhances a given raster image using ‘generative upscale’ tool, boosting resolution with a focus on refining small details and faces.
POST https://external.api.recraft.ai/v1/images/generativeUpscaleresponse = client.post(
path='/images/generativeUpscale',
cast_to=object,
options={'headers': {'Content-Type': 'multipart/form-data'}},
files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])
https://img.recraft.ai/DV4d9pMeq5lIluqS7m8qHyg-mb6hf5uCqEPPC8t8wy4/rs:fit:4740:3536:0/raw:1/plain/abs://external/images/fb576169-8a66-4270-a566-35713ad72020Body of a request should be a file in PNG format and parameters passed as content type multipart/form-data.
Upload a set of images to create a style reference.
POST https://external.api.recraft.ai/v1/stylesresponse = 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']){"id": "229b2a75-05e4-4580-85f9-b47ee521a00d"} Upload a set of images to create a style reference.
Returns information of the current user including credits balance.
GET https://external.api.recraft.ai/v1/users/meresponse = client.get(path='/users/me', cast_to=object)
print(response){
"credits": 1000,
"email": "[email protected]",
"id": "c18a1988-45e7-4c00-82c4-4ad7d3dbce3a",
"name": "Recraft Test"
}The generation process can be adjusted with a number of tweaks.
Color type is defined as an object with the following fields
response = client.images.generate(
prompt='race car on a track',
style='realistic_image',
extra_body={
'controls': {
'colors': [
{'rgb': [0, 255, 0]}
]
}
}
)
print(response.data[0].url)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).
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 an individual word composed of the following supported 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.
response = client.images.generate(
prompt='race car on a track',
style='realistic_image',
extra_body={
'text_layout': [
{
'text': 'HELLO',
'bbox': [[0.1, 0.2], [0.9, 0.2], [0.8, 0.7], [0.2, 0.6]],
},
{
'text': 'WORLD',
'bbox': [[-0.2, -0.1], [1.2, -0.1], [1.2, 1.1], [-0.2, 1.1]],
},
],
},
)
print(response.data[0].url)Generate AI images using cURL or Python and create your own styles programmatically.
curl https://external.api.recraft.ai/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-d '{
"prompt": "two race cars on a track",
"style": "digital_illustration",
"model": "recraftv3"
}'from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
response = client.images.generate(
prompt='two race cars on a track',
style='digital_illustration',
model='recraftv3',
)
print(response.data[0].url)curl https://external.api.recraft.ai/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-d '{
"prompt": "red point siamese cat",
"style": "realistic_image",
"size": "1280x1024"
}'from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
response = client.images.generate(
prompt='red point siamese cat',
style='realistic_image',
size='1280x1024',
)
print(response.data[0].url)curl https://external.api.recraft.ai/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-d '{
"prompt": "a monster with lots of hands",
"style": "digital_illustration",
"substyle": "hand_drawn"
}'from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
response = client.images.generate(
prompt='a monster with lots of hands',
style='digital_illustration',
extra_body={'substyle': 'hand_drawn'},
)
print(response.data[0].url)curl -X POST https://external.api.recraft.ai/v1/images/inpaint \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-F "prompt=moon" \
-F "style=digital_illustration" \
-F "[email protected]" -F "[email protected]"from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
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={
'style': 'digital_illustration',
'prompt': 'moon',
},
)
print(response['data'][0]['url'])
curl -X POST https://external.api.recraft.ai/v1/styles \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-F "style=digital_illustration" \
-F "[email protected]"
# response: {"id":"095b9f9d-f06f-4b4e-9bb2-d4f823203427"}
curl https://external.api.recraft.ai/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-d '{
"prompt": "wood potato masher",
"style_id": "095b9f9d-f06f-4b4e-9bb2-d4f823203427"
}'from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
style = client.post(
path='/styles',
cast_to=object,
options={'headers': {'Content-Type': 'multipart/form-data'}},
body={'style': 'digital_illustration'},
files={'file': open('image.png', 'rb')},
)
print(style['id'])
response = client.images.generate(
prompt='wood potato masher',
extra_body={'style_id': style['id']},
)
print(response.data[0].url)curl -X POST https://external.api.recraft.ai/v1/images/vectorize \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-F "[email protected]"from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
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'])curl -X POST https://external.api.recraft.ai/v1/images/removeBackground \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-F "response_format=b64_json" \
-F "[email protected]"from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
style = client.post(
path='/images/removeBackground',
cast_to=object,
options={'headers': {'Content-Type': 'multipart/form-data'}},
body={'response_format': 'b64_json'},
files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])curl -X POST https://external.api.recraft.ai/v1/images/clarityUpscale \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-F "response_format=b64_json" \
-F "[email protected]"from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
style = client.post(
path='/images/clarityUpscale',
cast_to=object,
options={'headers': {'Content-Type': 'multipart/form-data'}},
body={'response_format': 'b64_json'},
files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])curl -X POST https://external.api.recraft.ai/v1/images/generativeUpscale \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer $RECRAFT_API_TOKEN" \
-F "[email protected]"from openai import OpenAI
client = OpenAI(base_url='https://external.api.recraft.ai/v1', api_key=_RECRAFT_API_TOKEN)
style = client.post(
path='/images/generativeUpscale',
cast_to=object,
options={'headers': {'Content-Type': 'multipart/form-data'}},
files={'file': open('image.png', 'rb')},
)
print(response['image']['url'])- 1024x1024
- 1365x1024
- 1024x1365
- 1536x1024
- 1024x1536
- 1820x1024
- 1024x1820
- 1024x2048
- 2048x1024
- 1434x1024
- 1024x1434
- 1024x1280
- 1280x1024
- 1024x1707
- 1707x1024
