Name: Recraft 20B Text-to-Image Generator API
Brand: magicapi
SKU: api-magicapi-affordable-fast-image-api-recraft-ai-recraft-20b
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Text-to-Image Generator API - Fast Styled Images (Recraft 20B)

## Overview
Recraft 20B is a text-to-image model from Recraft. Its developer describes it as affordable and fast.

Send a text `prompt` and choose one of 26 `style` presets, from realistic photos to digital illustration styles such as 2D posters, pixel art and watercolor. Set the shape with `aspect_ratio` or `size`. Each request returns the URL of one image.

## Features
- **Style presets**: 8 realistic styles (`realistic_image` and variants such as `b_and_w`, `hdr`, `natural_light`, `studio_portrait`) and 18 digital illustration styles (such as `2d_art_poster`, `3d`, `hand_drawn`, `kawaii`, `pixel_art`, `voxel`, `watercolor`). The full list is in the table below.
- **Sizes**: 15 fixed sizes from `1024x1024` (default) up to `2048x1024` and `1024x2048`.
- **Aspect ratios**: `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `1:2`, `2:1`, `7:5`, `5:7`, `4:5`, `5:4`, `3:5`, `5:3`. When `aspect_ratio` is set, `size` is ignored.
- **Simple input**: only `prompt` is required.

## Use Cases
1. **Posters and banners**: illustrated posters and headers in a chosen style.
2. **Blog and social images**: quick illustrations for articles and posts at a low price per image.
3. **Game and app art**: pixel art, voxel or kawaii style assets for prototypes.
4. **Realistic scenes**: photo-style images with lighting presets such as `natural_light` or `studio_portrait`.

## Visual Examples
### Example Input
Prompt:

> A retro travel poster of a striped hot air balloon floating over rolling green hills, with the bold headline "api.market" across the top.

Style: `digital_illustration/2d_art_poster`

All other fields were left at their defaults (`aspect_ratio` not set, `size` `1024x1024`).

### Example Output
![Recraft 20B output for the retro travel poster prompt: a striped hot air balloon over green hills with an api.market headline](https://blog.api.market/wp-content/uploads/2026/10/recraft-20b-output-api-market.jpg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes |  |  | Text prompt for image generation |
| `aspect_ratio` | string | No | `Not set` | `Not set`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `1:2`, `2:1`, `7:5`, `5:7`, `4:5`, `5:4`, `3:5`, `5:3` | Aspect ratio of the generated image. When set, size is ignored. |
| `size` | string | No | `1024x1024` | `1024x1024`, `1365x1024`, `1024x1365`, `1536x1024`, `1024x1536`, `1820x1024`, `1024x1820`, `1024x2048`, `2048x1024`, `1434x1024`, `1024x1434`, `1024x1280`, `1280x1024`, `1024x1707`, `1707x1024` | Width and height of the generated image. Size is ignored if an aspect ratio is set. |
| `style` | string | No | `realistic_image` | `realistic_image`, `realistic_image/b_and_w`, `realistic_image/enterprise`, `realistic_image/hard_flash`, `realistic_image/hdr`, `realistic_image/motion_blur`, `realistic_image/natural_light`, `realistic_image/studio_portrait`, `digital_illustration`, `digital_illustration/2d_art_poster`, `digital_illustration/2d_art_poster_2`, `digital_illustration/3d`, `digital_illustration/80s`, `digital_illustration/engraving_color`, `digital_illustration/glow`, `digital_illustration/grain`, `digital_illustration/hand_drawn`, `digital_illustration/hand_drawn_outline`, `digital_illustration/handmade_3d`, `digital_illustration/infantile_sketch`, `digital_illustration/kawaii`, `digital_illustration/pixel_art`, `digital_illustration/psychedelic`, `digital_illustration/seamless`, `digital_illustration/voxel`, `digital_illustration/watercolor` | Style of the generated image. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.028 per API unit.
- **1 API unit = 1 output image.** Each request returns one image, so each successful request costs $0.028.
- Every style, size and aspect ratio is billed the same. The example request above cost $0.028.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/affordable-fast-image-api-recraft-ai-recraft-20b`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/affordable-fast-image-api-recraft-ai-recraft-20b/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "c303fbbc72c026aa4315e5efc5dd9d8a1dfb60927c84c8c32214cd1d39028701",
    "input": {
      "prompt": "A retro travel poster of a striped hot air balloon floating over rolling green hills, with the bold headline \"api.market\" across the top.",
      "style": "digital_illustration/2d_art_poster"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "m85zt9b7rnrmr0d17fvawh9r3c",
  "version": "c303fbbc72c026aa4315e5efc5dd9d8a1dfb60927c84c8c32214cd1d39028701",
  "status": "starting",
  "created_at": "2026-10-14T19:49:26.737Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/affordable-fast-image-api-recraft-ai-recraft-20b/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "m85zt9b7rnrmr0d17fvawh9r3c",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/recraft-20b-output-api-market.jpg",
  "error": null,
  "created_at": "2026-10-14T19:49:26.737Z",
  "started_at": "2026-10-14T19:49:27.737Z",
  "completed_at": "2026-10-14T19:49:41.737Z"
}
```

`output` is a single URL string pointing to the generated image.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `prompt` or a `style` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/affordable-fast-image-api-recraft-ai-recraft-20b";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "c303fbbc72c026aa4315e5efc5dd9d8a1dfb60927c84c8c32214cd1d39028701", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "prompt": "A retro travel poster of a striped hot air balloon floating over rolling green hills, with the bold headline \"api.market\" across the top.",
  "style": "digital_illustration/2d_art_poster"
}).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/affordable-fast-image-api-recraft-ai-recraft-20b"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "c303fbbc72c026aa4315e5efc5dd9d8a1dfb60927c84c8c32214cd1d39028701", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")

print(create_and_wait_for_prediction({
  "prompt": "A retro travel poster of a striped hot air balloon floating over rolling green hills, with the bold headline \"api.market\" across the top.",
  "style": "digital_illustration/2d_art_poster"
}))
```

## FAQ
- **Which style should I pick?**
  - Use `realistic_image` (the default) or one of its variants for photo-style results, and a `digital_illustration` style for illustrations. The style name is sent as the full value, for example `digital_illustration/pixel_art`.
- **What happens if I set both `size` and `aspect_ratio`?**
  - `aspect_ratio` wins and `size` is ignored. Leave `aspect_ratio` at `Not set` to use an exact `size`.
- **Can I reproduce the same image?**
  - There is no seed field, so each request creates a new image even with the same prompt.
- **How many images does one request return, and what does it cost?**
  - One image, returned as a single URL in `output`. It costs $0.028.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Generate images from text with Recraft 20B in 26 styles, including realistic photos, 2D posters, pixel art and watercolor. $0.028 per image, pay as you go.