controls and text_layout objects. Each tool has its own page with a runnable request.
Authentication
All requests need anAuthorization: Bearer RECRAFT_API_TOKEN header. See the Quickstart to get a token.
Python examples on this page come in two variants: plain HTTP with requests, and the OpenAI Python library (see Clients and SDKs for how it maps to the Recraft API).
All endpoints
Base URL:https://external.api.recraft.ai/v1. Every endpoint takes JSON (images as URLs or data URLs) or multipart/form-data (images as files).
Raster / vector prices are for
recraftv3 / recraftv3_vector. See Pricing for every model.
Image inputs and results
The API accepts input images and returns generated images in several formats, so you can pick the one that fits your client best:- Inputs — send an image or a mask as a multipart file (
image,mask,file, …), or reference it in a JSON body by URL or data URL in the matching*_urlfield. - Results — choose how generated images come back with
response_format: a downloadurl(default), Base64 inb64_json, or raw bytes in amultipartresponse. - Image format — raster images come back as lossless WebP by default, pass
image_format: pngto get PNG instead.
For the best latency use
response_format: multipart.Generate image
Creates an image given a prompt.model and style values to a single output type:
/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.
/generations endpoint remains available and accepts any supported model or style.
Example
Parameters
Note: when using the V4 Styles models, a style must be specified — either via
style_id, or via style references. A request without one is rejected.
Note: the V4.1 Flash model (recraftv4_1_flash) does not support styles: style, style_id, style_match, and style references are not supported with it.
Style references
Instead of referencing an existing style bystyle_id, you can attach style reference images directly to a generation request. When present, the server creates a private style from these images and applies it to the generation. The resolved style’s id is returned as style_id in the response, so you can reuse it in later requests.
- Provide the images as
style_references(multipart file parts, any field name) or asstyle_reference_urls(URLs or data URLs, JSON only). - Images must be in PNG, JPG, or WEBP format. The maximum number of images is 10, and their total size is limited to 64 MB (each file must also be under the 20 MB upload limit).
- V2, V3, V4 and V4.1 models (including the dedicated V4 Styles model, but not V4.1 Flash) support style references; when no
modelis specified the request defaults torecraftv4_styles. Combining style references withstyle_idis rejected. - Billing is composite: creating the style is charged once, in addition to the per-image generation cost. The response
creditsfield is the sum of both.
Example
Create style
Upload a set of images to create a style reference.Example
Parameters
Upload a set of images to create a style reference.
Note: at least one of
files, image_urls, or source_styles must be provided.
Manage styles
Four endpoints manage the custom styles of your account.Example
Get user information
Returns information of the current user including credits balance.Example
Auxiliary
Controls
The generation process can be adjusted with a number of tweaks.Colors
A color is an object with the following fields:
A
colors array may contain at most 10 colors.
Color objects are used in two places:
colorsandbackground_colorin Controls — preferable colors for a single generation request;colorsandbackground_colorin thepaletteparameter of Create style — the color palette stored with a style.
palette (in multipart requests, the palette is passed as repeated palette[colors][][rgb][] and palette[background_color][rgb][] fields carrying the RGB values; weights can be set in JSON requests only):
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.
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: