---
name: recraft
description: Use when generating, editing, or transforming images via REST API.
  Agents should reach for this skill when building image generation workflows,
  integrating AI image tools into applications, working with vector or raster
  outputs, or implementing image editing operations like inpainting, upscaling,
  or background removal.
metadata:
  mintlify-proj: recraft
  version: "1.0"
---

# Recraft API Skill

## Product summary

Recraft is a REST API for generating and editing high-quality raster and vector images using AI models. Agents use it to create images from text prompts, edit existing images, vectorize rasters, upscale, remove backgrounds, and apply custom styles. The API is pay-as-you-go (1 USD = 1,000 API units), with models ranging from $0.007 (V4.1 Flash) to $0.30 per image. Base URL: `https://external.api.recraft.ai/v1`. Authenticate with Bearer token in the `Authorization` header. Primary docs: https://www.recraft.ai/docs/api-reference/introduction

## When to use

Reach for this skill when:
- **Generating images from text**: User asks to create an image, logo, illustration, or design from a description
- **Editing existing images**: User wants to modify, transform, or enhance an image (image-to-image, inpainting, outpainting, background changes)
- **Converting formats**: User needs to vectorize a raster image (PNG/JPG → SVG) or upscale resolution
- **Batch operations**: User needs to generate multiple image variations or apply operations at scale
- **Style consistency**: User wants to apply a consistent visual style across multiple generated images
- **Building integrations**: Integrating image generation into an application, workflow, or agent system
- **MCP integration**: User is connecting Recraft to Claude, Cursor, or other MCP-compatible clients

Do not use this skill for: image hosting, storage, or retrieval; account management; billing operations; or authentication setup beyond token creation.

## Quick reference

### Authentication & Setup
```
Base URL: https://external.api.recraft.ai/v1
Header: Authorization: Bearer $RECRAFT_API_TOKEN
Token: Create at https://www.recraft.ai/app/api/api-keys
Balance: Check with GET /users/me
```

### Core Endpoints
| Operation | Endpoint | Cost | Use case |
|-----------|----------|------|----------|
| Generate image | `POST /images/generations` | $0.007–$0.30 | Create raster or vector images from prompt |
| Image to image | `POST /images/imageToImage` | $0.04–$0.08 | Transform image with prompt + strength |
| Inpaint | `POST /images/inpaint` | $0.04–$0.08 | Edit selected region of image |
| Outpaint | `POST /images/outpaint` | $0.04–$0.08 | Expand image beyond original boundaries |
| Remove background | `POST /images/removeBackground` | $0.01 | Strip background from image |
| Replace background | `POST /images/replaceBackground` | $0.04–$0.08 | Generate new background from prompt |
| Vectorize | `POST /images/vectorize` | $0.01 | Convert raster to SVG |
| Crisp upscale | `POST /images/crispUpscale` | $0.004 | Increase resolution without regeneration |
| Creative upscale | `POST /images/creativeUpscale` | $0.25 | Upscale + regenerate details |
| Enhance details | `POST /images/enhance` | $0.21 | Improve detail quality (V4.1 Pro only) |
| Create style | `POST /styles` | $0.005 | Save custom style from reference images |
| Enhance prompt | `POST /prompts/enhance` | $0.01 | Expand short prompt to detailed version |

### Model Selection
| Model | Price | Output | Best for |
|-------|-------|--------|----------|
| V4.1 Flash | $0.007 | Raster only | Speed + cost (1.3s, no styles) |
| V4.1 (default) | $0.035–$0.30 | Raster/Vector | Photorealism, illustration, short prompts |
| V4 Styles | $0.035–$0.12 | Raster/Vector | Style-consistent generation from references |
| V4 | $0.04–$0.30 | Raster/Vector | Design taste, production-grade vectors |
| V3 | $0.04–$0.08 | Raster/Vector | Text placement, inpainting, outpainting |
| V2 | $0.022–$0.044 | Raster/Vector | Icons, minimalistic styles, cheapest vector |

### Rate Limits
- 100 images per minute per user
- 5 requests per second per user
- Image URLs valid ~24 hours (download immediately)
- Input images: PNG/JPG/WEBP/SVG, <20 MB, up to 16 MP, 256–4096 px sides

### Response Format
```json
{
  "created": 1759140000,
  "credits": 35,
  "data": [
    {
      "image_id": "uuid",
      "url": "https://..."
    }
  ]
}
```
- `credits`: API units charged for request
- `url`: Temporary download link (24 hours)
- `data`: Array with one entry per image (n parameter)

## Decision guidance

### When to use which model

| Scenario | Model | Reason |
|----------|-------|--------|
| Need fastest generation, cost-sensitive | V4.1 Flash | $0.007/image, 1.3s, no style overhead |
| Default choice, balanced quality/cost | V4.1 | $0.035/image, handles all prompt types, supports styles |
| Must match visual style from examples | V4 Styles | Dedicated style matching, no training required |
| Need production-grade vector output | V4 or V4.1 | Superior vector quality and design taste |
| Require text placement or inpainting | V3 | Only model with text_layout parameter |
| Budget-constrained vector work | V2 | $0.022/image raster, $0.044/vector, icon-optimized |

### When to use which editing operation

| Goal | Operation | Strength/Parameters |
|------|-----------|-------------------|
| Subtle changes (lighting, mood) | Image to image | strength: 0.1–0.3 |
| Moderate transformation | Image to image | strength: 0.4–0.6 |
| Major style change | Image to image | strength: 0.7–1.0 |
| Edit specific region | Inpaint | Provide mask + prompt |
| Expand beyond edges | Outpaint | Specify direction + prompt |
| Remove unwanted object | Erase region | Provide mask |
| Increase resolution only | Crisp upscale | No regeneration |
| Improve detail + resolution | Creative upscale | Regenerates details |

### Response format choice

| Format | Use when | Trade-off |
|--------|----------|-----------|
| `url` (default) | Downloading later, storing URLs | Slight latency, URLs expire in 24h |
| `b64_json` | Embedding inline, immediate processing | Larger response payload |
| `multipart` | Lowest latency, streaming | Requires multipart parsing |

## Workflow

### Generate an image from scratch
1. **Prepare the prompt**: Write a clear description (subject, composition, style, mood). Use core principles: subject (what), composition (how arranged), context (where/when).
2. **Choose model**: Default to V4.1 unless you need speed (Flash), styles (V4 Styles), or text placement (V3).
3. **Set parameters**: Decide size, style (optional), number of images (n), and response format.
4. **Make request**: POST to `/images/generations` with prompt, model, and parameters.
5. **Handle response**: Extract `data[0].url`, download immediately (24h expiry), check `credits` for cost.
6. **Verify output**: Confirm image matches intent. If not, iterate with adjusted prompt or lower artistic level.

### Edit an existing image
1. **Assess the change**: Determine if you need subtle edits (low strength), major transformation (high strength), or region-specific work (inpaint/outpaint).
2. **Prepare input**: Upload image as file or provide URL. For inpaint/outpaint, prepare mask (grayscale, pure black/white).
3. **Write edit prompt**: Describe only what should change, not the entire image.
4. **Choose operation**: Image-to-image for full transformation, inpaint for regions, outpaint for expansion.
5. **Set strength**: Lower (0.1–0.3) for subtle changes, higher (0.7–1.0) for major rewrites.
6. **Make request**: POST to appropriate endpoint with image, prompt, strength, and model.
7. **Download result**: Extract URL, download before 24h expiry.

### Create and reuse a custom style
1. **Gather reference images**: Collect 1–10 images (PNG/JPG/WEBP) that define your desired style (max 64 MB total).
2. **Create style**: POST to `/styles` with reference images and model (e.g., `recraftv4_styles`).
3. **Store style_id**: Save the returned UUID for reuse.
4. **Generate with style**: Include `style_id` in generation requests to apply style consistently.
5. **Manage styles**: List styles with GET `/styles`, delete with DELETE `/styles/{style_id}`.

### Vectorize and upscale workflow
1. **Vectorize raster**: POST raster image to `/images/vectorize` ($0.01). Returns SVG.
2. **Upscale raster**: POST to `/images/crispUpscale` ($0.004) for resolution only, or `/images/creativeUpscale` ($0.25) to regenerate details.
3. **Download result**: Extract URL, verify format (SVG for vectorize, PNG/WebP for upscale).

## Common gotchas

- **Token not set**: Always export `RECRAFT_API_TOKEN` before making requests. Requests without valid token return 401.
- **Insufficient balance**: Requests fail if account has no API units. Check balance with GET `/users/me` before large batches.
- **Image URLs expire**: Downloaded URLs are valid ~24 hours. Download immediately; don't store URLs for later.
- **Rate limit hits**: 100 images/min and 5 requests/sec per user. Space requests or implement exponential backoff on 429 responses.
- **Wrong model for operation**: V4.1 Flash doesn't support styles. V3 is required for text_layout. V2 is cheapest but lower quality. Check model compatibility before requesting.
- **Prompt too long**: Max prompt length varies by model (typically 1000–2000 chars). Truncate or use enhance_prompt endpoint if needed.
- **Mask format wrong**: Inpaint/outpaint masks must be grayscale with pure black (0) or white (255) pixels, same size as image. Gray pixels are rejected.
- **Style references not applied**: Style references create a private style on-the-fly. If you want reusable styles, create with POST `/styles` first and use `style_id`.
- **Multipart vs JSON**: Use multipart for file uploads, JSON for URLs. Don't mix (e.g., `image` file + `image_url` in same request).
- **Strength parameter ignored**: Image-to-image requires `strength` (0–1). Omitting it causes error. Low strength (0.1) keeps original, high (1.0) ignores original.
- **Vector output not SVG**: Ensure model name ends in `_vector` (e.g., `recraftv4_1_vector`) to get SVG. Raster models return PNG/WebP.
- **Artistic level confusion**: Only V3 supports `artistic_level` parameter. V4/V4.1 ignore it. Use `controls` object for V4/V4.1 tweaks.

## Verification checklist

Before submitting work with Recraft API:

- [ ] **Token valid**: Confirmed `RECRAFT_API_TOKEN` is set and account has positive balance (GET `/users/me`).
- [ ] **Model chosen**: Selected appropriate model for use case (V4.1 default, Flash for speed, V3 for text, V4 Styles for consistency).
- [ ] **Prompt clear**: Prompt includes subject, composition, and style intent. Tested with short and long versions.
- [ ] **Parameters correct**: Verified size, n (number of images), response_format, and model-specific params (style_id, strength, mask, etc.).
- [ ] **Input images valid**: If using image input, confirmed PNG/JPG/WEBP/SVG, <20 MB, 256–4096 px sides, proper format for operation.
- [ ] **Masks correct**: For inpaint/outpaint, verified mask is grayscale with pure black/white pixels, same dimensions as image.
- [ ] **Rate limits respected**: Spaced requests to stay under 100 images/min and 5 req/sec per user.
- [ ] **URLs downloaded**: Downloaded all image URLs immediately (don't rely on 24h expiry).
- [ ] **Cost tracked**: Checked `credits` field in response to confirm expected cost.
- [ ] **Error handling**: Implemented retry logic for 5xx errors and exponential backoff for rate limits.
- [ ] **Output verified**: Confirmed generated/edited images match intent before delivery.

## Resources

- **Comprehensive navigation**: https://www.recraft.ai/docs/llms.txt — Full page-by-page listing for agent reference
- **API Endpoints reference**: https://www.recraft.ai/docs/api-reference/endpoints — Complete parameter documentation for all operations
- **Prompt engineering guide**: https://www.recraft.ai/docs/prompt-engineering-guide/introduction — Core and artistic principles for effective prompting
- **Model comparison**: https://www.recraft.ai/docs/api-reference/models/overview — Detailed specs, pricing, and use cases for each model

---

> For additional documentation and navigation, see: https://www.recraft.ai/docs/llms.txt