Set up Recraft with an AI agent

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

{
  "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