Skip to main content
Every Recraft API endpoint at a glance, plus the full reference for image generation, styles, and the shared controls and text_layout objects. Each tool has its own page with a runnable request.

Authentication

All requests need an Authorization: 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 *_url field.
  • Results — choose how generated images come back with response_format: a download url (default), Base64 in b64_json, or raw bytes in a multipart response.
  • Image format — raster images come back as lossless WebP by default, pass image_format: png to get PNG instead.
Both are described in detail in Image inputs and results.
For the best latency use response_format: multipart.

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

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

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