Skip to main content
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:
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: 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.
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:
  • /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

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. Hint: if OpenAI Python Library is used, non-standard parameters can be passed using the extra_body argument. For example:

Style references

Instead of referencing an existing style by style_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 as style_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 10 MB upload limit).
  • V2, V3, V4 and V4.1 models (including the dedicated V4 Styles model) support style references; when no model is specified the request defaults to recraftv4_styles. Combining style references with style_id is rejected.
  • Billing is composite: creating the style is charged once, in addition to the per-image generation cost. The response credits field is the sum of both.

Example

Create style

Upload a set of images to create a style reference.

Example

Response

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.

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, Recraft V4 and Recraft V4.1 models (raster and vector).

Example

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.

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.

Example

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.

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.

Example

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.

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.

Example

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.

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.

Example

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.

Vectorize image

Converts a given raster image to SVG format.

Example

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.

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.

Example

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.

Crisp upscale

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

Example

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 32 pixels.

Creative upscale

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

Example

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.

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.

Example

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

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.

Example

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.

Explore

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

Example

Parameters

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.

Example

Parameters

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.

Example

Parameters

Get user information

Returns information of the current user including credits balance.

Example

Response

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:
  • colors and background_color in Controls — preferable colors for a single generation request;
  • colors and background_color in the palette parameter of Create style — the color palette stored with a style.
Example A generation with two weighted preferable colors and a desired background color:
Creating a style with a stored 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:
Any character not listed above will result in validation errors. Example