# Recraft API
> Recraft pictures and real SVG vectors from a description, versions V4.1 and V4.1 Pro. Edits of your picture: replacing and erasing an area by a mask, extending the frame, replacing the background. Also similar variants, conversion to vector, background removal and upscaling.
Developer: Recraft
Model key in the API: `recraft`
## Connect in three steps
1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model.
2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you.
3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files.
## Ready-to-use code
Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded.
```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "recraft",
"settings": {
"mode": "text_to_image",
"prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
"engine": "v4_1",
"aspect_ratio": "3:2"
}
}'
curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python
import time
import requests
API = "https://api.cyhub.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
body = {
"model": "recraft",
"settings": {
"mode": "text_to_image",
"prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
"engine": "v4_1",
"aspect_ratio": "3:2",
},
}
response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
time.sleep(5)
task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```
```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };
const body = {
"model": "recraft",
"settings": {
"mode": "text_to_image",
"prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
"engine": "v4_1",
"aspect_ratio": "3:2"
}
};
async function main() {
let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
if (!response.ok) throw new Error(await response.text());
let task = await response.json();
while (task.status === "queued" || task.status === "running") {
await new Promise((resolve) => setTimeout(resolve, 5000));
response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
task = await response.json();
}
console.log(task.status, task.result);
}
main();
```
[Get a key](https://cyhub.ai/cabinet/keys)
## Price before the run
Prices as of 15.10.2026: from 1 ₽. POST /v1/price shows the exact price of your settings.
Send the same settings to POST /v1/price: the response shows the price of the run without charging you.
```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "recraft",
"settings": {
"mode": "text_to_image",
"prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
"engine": "v4_1",
"aspect_ratio": "3:2"
}
}'
```
- amount_minor: the price of the run in minor units (kopecks for rubles)
- currency: the wallet currency
- available_minor: how much your balance has for new tasks right now
## Picture from a description
> Draws a picture from scratch by the description. Recraft handles in-frame text well.
Value of the mode field: `text_to_image`
Price in this mode from 6 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `prompt` (Required)
What to draw. Put the words that must appear on the picture in quotes. With the V3 and V2 engines no longer than 1000 characters.
- Type: String
- Minimum characters: 1
- Maximum characters: 2000
#### `engine` (Optional)
Engine; the price depends on it. V4.1: the best balance. V4.1 Pro: top quality, larger (a 2048 by 2048 square instead of 1024 by 1024) and noticeably pricier. V3: supports preset styles. V2: the cheapest.
- Type: String
- Allowed values: `v4_1` (V4.1 (best balance)), `v4_1_pro` (V4.1 Pro (top quality))
- Default: `"v4_1"`
#### `style` (Optional)
A preset style: photorealism or illustration. Only V3 and V2 have them; with V4.1 describe the manner in words.
- Type: String
- Allowed values: `none`
- The set depends on `engine`.
- Default: `"none"`
#### `aspect_ratio` (Optional)
Aspect ratio of the frame.
- Type: String
- Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- Default: `"1:1"`
#### `count` (Optional)
How many variants to make at once, 1 to 6. Each one is paid separately.
- Type: Integer
- Minimum: 1
- Maximum: 6
- Default: `1`
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
A sign with lettering
```json
{
"model": "recraft",
"settings": {
"mode": "text_to_image",
"prompt": "Деревянная вывеска кофейни с надписью «Утро», тёплый вечерний свет",
"engine": "v4_1",
"aspect_ratio": "3:2"
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The pictures come as lossless WebP files, as many as set in count.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 to 6 | As many as set in count. |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Vector from a description
> Draws a real SVG vector from scratch: logos, icons, flat illustrations.
Value of the mode field: `text_to_vector`
Price in this mode from 12 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `prompt` (Required)
What to draw. Put the words that must appear on the picture in quotes. With the V3 and V2 engines no longer than 1000 characters.
- Type: String
- Minimum characters: 1
- Maximum characters: 2000
#### `engine` (Optional)
Engine; the price depends on it. V4.1: the best balance. V4.1 Pro: top quality, noticeably pricier. V3: the previous generation. V2: the cheapest.
- Type: String
- Allowed values: `v4_1` (V4.1 (best balance)), `v4_1_pro` (V4.1 Pro (top quality))
- Default: `"v4_1"`
#### `aspect_ratio` (Optional)
Aspect ratio of the frame.
- Type: String
- Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- Default: `"1:1"`
#### `count` (Optional)
How many variants to make at once, 1 to 6. Each one is paid separately.
- Type: Integer
- Minimum: 1
- Maximum: 6
- Default: `1`
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
An icon
```json
{
"model": "recraft",
"settings": {
"mode": "text_to_vector",
"prompt": "Плоская иконка ракеты в два цвета, толстый контур",
"engine": "v4_1",
"aspect_ratio": "1:1"
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The result is SVG: a real vector that scales without loss and opens in an editor. As many files as set in count.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `document` | svg | 1 to 6 | As many as set in count. |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "document",
"filename": "result.svg",
"size": 2097152,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Rework a picture
> Your picture plus a description: the model draws a new one keeping the composition and colours of the source. strength sets how far to go.
Value of the mode field: `image_to_image`
Price in this mode from 6 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
#### `prompt` (Required)
What the picture should become, up to 1000 characters. Name the objects: the model draws by the description and does not get references like "the same object".
- Type: String
- Minimum characters: 1
- Maximum characters: 1000
#### `strength` (Optional)
How far to go from the source: 0.2 a light touch, 0.5 a noticeable rework, 0.8 almost from scratch.
- Type: String
- Allowed values: `0.2` (Light touch), `0.5` (Noticeable rework), `0.8` (Almost from scratch)
- Default: `"0.5"`
#### `count` (Optional)
How many variants to make at once, 1 to 6. Each one is paid separately.
- Type: Integer
- Minimum: 1
- Maximum: 6
- Default: `1`
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
A different interior
```json
{
"model": "recraft",
"settings": {
"mode": "image_to_image",
"image_urls": [
"https://example.com/living-room.jpg"
],
"prompt": "Гостиная в скандинавском стиле: светлый диван, дубовый стол, растения в горшках",
"strength": "0.5"
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The pictures come as lossless WebP files, as many as set in count.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 to 6 | As many as set in count. |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Replace an area
> Repaints the part of the picture marked by the mask according to the description. The rest stays as it was.
Value of the mode field: `inpaint`
Price in this mode from 6 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
#### `mask_urls` (Required)
One URL of the mask: a grayscale picture of exactly the same size as the source. White marks what to repaint, black marks what to keep.
- Type: List (String, uri)
- Maximum items: 1
#### `prompt` (Required)
A description of the whole picture as it should end up, not just the marked piece, up to 1000 characters. A short order like "write GG here" will only wipe the area.
- Type: String
- Minimum characters: 1
- Maximum characters: 1000
#### `count` (Optional)
How many variants to make at once, 1 to 6. Each one is paid separately.
- Type: Integer
- Minimum: 1
- Maximum: 6
- Default: `1`
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
- Mask: a grayscale PNG or JPEG (one channel, no colour or transparency) of exactly the same size as the source. White marks what changes, black marks what stays. A colour mask will not do, even if it looks black and white.
- PNG is better: only pure black and pure white are expected, and JPEG compression leaves grey pixels on the edges.
- We download the picture and the mask ourselves: the URL must return the file directly, without a redirect.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
| `mask_urls` | Images | jpeg, jpg, png | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
A cactus on the windowsill
```json
{
"model": "recraft",
"settings": {
"mode": "inpaint",
"image_urls": [
"https://example.com/room.jpg"
],
"mask_urls": [
"https://example.com/room-mask.png"
],
"prompt": "Светлая комната, на подоконнике стоит глиняный горшок с кактусом"
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The pictures come as lossless WebP files, as many as set in count.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 to 6 | As many as set in count. |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Erase something
> Removes what the mask marks and fills in the background behind it. No description needed.
Value of the mode field: `erase`
Price in this mode from 1 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
#### `mask_urls` (Required)
One URL of the mask: a grayscale picture of exactly the same size as the source. White marks what to erase, black marks what to keep.
- Type: List (String, uri)
- Maximum items: 1
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
- Mask: a grayscale PNG or JPEG (one channel, no colour or transparency) of exactly the same size as the source. White marks what changes, black marks what stays. A colour mask will not do, even if it looks black and white.
- PNG is better: only pure black and pure white are expected, and JPEG compression leaves grey pixels on the edges.
- We download the picture and the mask ourselves: the URL must return the file directly, without a redirect.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
| `mask_urls` | Images | jpeg, jpg, png | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
Remove a passer-by
```json
{
"model": "recraft",
"settings": {
"mode": "erase",
"image_urls": [
"https://example.com/beach.jpg"
],
"mask_urls": [
"https://example.com/beach-mask.png"
]
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The picture comes as a lossless WebP file.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 | |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Extend the frame
> Draws the picture further out by the given number of pixels.
Value of the mode field: `outpaint`
Price in this mode from 6 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
#### `prompt` (Required)
What should appear in the added part, up to 1000 characters.
- Type: String
- Minimum characters: 1
- Maximum characters: 1000
#### `expand_left` (Optional)
How many pixels to add on the left, 0 to 1024.
- Type: Integer
- Minimum: 0
- Maximum: 1024
- Default: `0`
#### `expand_right` (Optional)
How many pixels to add on the right, 0 to 1024.
- Type: Integer
- Minimum: 0
- Maximum: 1024
- Default: `0`
#### `expand_top` (Optional)
How many pixels to add on the top, 0 to 1024.
- Type: Integer
- Minimum: 0
- Maximum: 1024
- Default: `0`
#### `expand_bottom` (Optional)
How many pixels to add on the bottom, 0 to 1024.
- Type: Integer
- Minimum: 0
- Maximum: 1024
- Default: `0`
#### `count` (Optional)
How many variants to make at once, 1 to 6. Each one is paid separately.
- Type: Integer
- Minimum: 1
- Maximum: 6
- Default: `1`
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
- At least one side above zero. The final frame is at most 4096 pixels on each side.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
Wider on both sides
```json
{
"model": "recraft",
"settings": {
"mode": "outpaint",
"image_urls": [
"https://example.com/portrait.jpg"
],
"prompt": "Песчаный пляж и спокойное море до горизонта",
"expand_left": 512,
"expand_right": 512
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The pictures come as lossless WebP files, as many as set in count.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 to 6 | As many as set in count. |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Replace the background
> The object stays, and Recraft finds the background itself and rewrites it by the description.
Value of the mode field: `replace_background`
Price in this mode from 6 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
#### `prompt` (Required)
What the background should become, up to 1000 characters.
- Type: String
- Minimum characters: 1
- Maximum characters: 1000
#### `count` (Optional)
How many variants to make at once, 1 to 6. Each one is paid separately.
- Type: Integer
- Minimum: 1
- Maximum: 6
- Default: `1`
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
A product on marble
```json
{
"model": "recraft",
"settings": {
"mode": "replace_background",
"image_urls": [
"https://example.com/bottle.png"
],
"prompt": "Мраморная столешница, мягкий утренний свет"
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The pictures come as lossless WebP files, as many as set in count.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 to 6 | As many as set in count. |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Background by mask
> Like replacing the background, but the mask sets where the background is.
Value of the mode field: `generate_background`
Price in this mode from 6 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
#### `mask_urls` (Required)
One URL of the mask: a grayscale picture of exactly the same size as the source. White marks where to draw the new background, black marks the object that stays.
- Type: List (String, uri)
- Maximum items: 1
#### `prompt` (Required)
What the background should become, up to 1000 characters.
- Type: String
- Minimum characters: 1
- Maximum characters: 1000
#### `count` (Optional)
How many variants to make at once, 1 to 6. Each one is paid separately.
- Type: Integer
- Minimum: 1
- Maximum: 6
- Default: `1`
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
- Mask: a grayscale PNG or JPEG (one channel, no colour or transparency) of exactly the same size as the source. White marks what changes, black marks what stays. A colour mask will not do, even if it looks black and white.
- PNG is better: only pure black and pure white are expected, and JPEG compression leaves grey pixels on the edges.
- We download the picture and the mask ourselves: the URL must return the file directly, without a redirect.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
| `mask_urls` | Images | jpeg, jpg, png | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
A sneaker by a wall
```json
{
"model": "recraft",
"settings": {
"mode": "generate_background",
"image_urls": [
"https://example.com/sneaker.png"
],
"mask_urls": [
"https://example.com/sneaker-mask.png"
],
"prompt": "Бетонная стена с граффити, дневной свет"
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The pictures come as lossless WebP files, as many as set in count.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 to 6 | As many as set in count. |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Similar variants
> A few variations of your picture: details, object positions and composition change, the overall idea stays. No description needed.
Value of the mode field: `variate`
Price in this mode from 6 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
#### `aspect_ratio` (Optional)
Aspect ratio of the variants.
- Type: String
- Allowed values: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `2:1`, `1:2`
- Default: `"1:1"`
#### `count` (Optional)
How many variants to make at once, 1 to 6. Each one is paid separately.
- Type: Integer
- Minimum: 1
- Maximum: 6
- Default: `1`
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
Three variants of a character
```json
{
"model": "recraft",
"settings": {
"mode": "variate",
"image_urls": [
"https://example.com/mascot.png"
],
"aspect_ratio": "1:1",
"count": 3
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The pictures come as lossless WebP files, as many as set in count.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 to 6 | As many as set in count. |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Convert to vector
> Turns the picture into a real SVG vector. No description needed.
Value of the mode field: `vectorize`
Price in this mode from 2 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
A logo to vector
```json
{
"model": "recraft",
"settings": {
"mode": "vectorize",
"image_urls": [
"https://example.com/logo.png"
]
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The result is one SVG file.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `document` | svg | 1 | |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "document",
"filename": "result.svg",
"size": 2097152,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Remove the background
> Cuts out the object and removes the background. No description needed.
Value of the mode field: `remove_background`
Price in this mode from 2 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
A product without background
```json
{
"model": "recraft",
"settings": {
"mode": "remove_background",
"image_urls": [
"https://example.com/product.jpg"
]
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- A picture with a transparent background, a lossless WebP file.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 | |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Crisp upscale
> Makes the picture larger: lines stay sharp and nothing new appears. No description needed.
Value of the mode field: `upscale_crisp`
Price in this mode from 1 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 32 to 4096 pixels.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
Enlarge a small picture
```json
{
"model": "recraft",
"settings": {
"mode": "upscale_crisp",
"image_urls": [
"https://example.com/small.png"
]
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The picture comes as a lossless WebP file.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 | |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## Creative upscale
> Makes the picture larger and invents fine details: skin pores, stray hairs, fabric grain. Saves small or blurry sources but may rewrite details its own way. No description needed.
Value of the mode field: `upscale_creative`
Price in this mode from 36 ₽.
### Parameters
Model parameters go inside settings. Omitted optional fields take their default values.
#### `image_urls` (Required)
One URL of the source picture.
- Type: List (String, uri)
- Maximum items: 1
Parameters not listed here are not accepted: the response is 422 unknown_setting.
### Input
- The picture is a URL of a JPEG, PNG or WebP file up to 10 MB, at most 16 megapixels, each side from 256 to 4096 pixels.
| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 10 MB |
[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)
### Request example
Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.
An old photo made larger
```json
{
"model": "recraft",
"settings": {
"mode": "upscale_creative",
"image_urls": [
"https://example.com/old-photo.jpg"
]
}
}
```
The price is calculated when the task is accepted, currency `RUB`.
[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)
### Output
- Usually ready in a few seconds to a minute.
- The picture comes as a lossless WebP file.
| Kind | Formats | How many | Note |
|---|---|---|---|
| `image` | webp | 1 | |
A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.
```json
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "succeeded",
"finished_at": "2026-10-01T12:03:41+00:00",
"result": {
"caption": "Caption of the result: the model and its settings",
"texts": [],
"files_expire_at": "2026-10-08T12:03:41+00:00",
"files_expired": false,
"artifacts": [
{
"index": 0,
"kind": "image",
"filename": "image.webp",
"size": 1843200,
"caption": "",
"download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
}
]
}
}
```
[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)
## See also
- [Recraft: features and prices](https://api.cyhub.ai/models/recraft)
- Other versions: [Recraft V3 API](https://api.cyhub.ai/en/models/recraft-v3/api.md), [Recraft V2 API](https://api.cyhub.ai/en/models/recraft-v2/api.md)
- Similar models: [GPT Image 2.5 API](https://api.cyhub.ai/en/models/gpt-image-2-5/api.md), [Nano Banana Pro API](https://api.cyhub.ai/en/models/nano-banana-pro/api.md), [Nano Banana 2 Lite API](https://api.cyhub.ai/en/models/nano-banana-2-lite/api.md), [Midjourney 8.2 API](https://api.cyhub.ai/en/models/midjourney/api.md), [Grok Imagine 2.0 API](https://api.cyhub.ai/en/models/grok-imagine-2/api.md), [Seedream 5.0 PRO API](https://api.cyhub.ai/en/models/seedream-5-pro/api.md)
- [API documentation](https://api.cyhub.ai/docs.md?lang=en)
- [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en)