Recraft API: Access, Endpoints and Style Consistency

Recraft publishes an official API that any account with a funded unit balance can call, and everything is REST against one base URL: https://external.api.recraft.ai/v1. Two questions decide whether it fits your pipeline — which model line you send, and how a style is expressed in the request body.

What the official Recraft API exposes

Recraft documents 20 models across five families as available in the API — V2, V3, V4, V4.1 and the separate V4 Styles line — with fifteen capabilities on top: generation, style creation, editing and masking, background work, vectorization, upscaling, remix, prompt enhancement, and an account call that returns your remaining balance.

Everything is REST, and Recraft recommends the OpenAI Python library with a warning attached: not all parameters are supported, some mean something different, and others may be quietly ignored. A parameter that never arrives without raising an error is the worst class of bug. The Recraft topic hub carries the model-family picture.

Getting a token and where the endpoints live

The authentication header

Tokens are Bearer tokens created at app.recraft.ai/profile/api, sent as Authorization: Bearer $RECRAFT_API_TOKEN. The generate button appears only while your API units balance is above zero, and every token you create draws on that one balance.

The endpoint surface

Every documented operation is an HTTP POST on the same host. Three response shapes cover the surface: /v1/images/generations answers with data[].url, vectorize, background removal and both upscalers answer with image.url, and /v1/styles answers with {"id": "..."}.

Your first generation request

# Requires curl and jq.
# 1. Recraft V4.1 is the documented default, so `model` is optional here.
curl https://external.api.recraft.ai/v1/images/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -d '{
        "prompt": "four race cars on a track, editorial light",
        "model": "recraftv4_1",
        "n": 2,
        "response_format": "url"
    }'

# 2. A curated style goes in `style` by name, with the model pinned to the
#    line that documents that name.
curl https://external.api.recraft.ai/v1/images/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -d '{
        "prompt": "a monster with lots of hands",
        "model": "recraftv3",
        "style": "Hand-drawn",
        "style_match": "regular"
    }'

Four field facts carry the weight. n accepts 1 to 6 and defaults to 1. model defaults to recraftv4_1, and the _vector, _pro and _utility suffixes select variants of that family. size takes WxH or a ratio such as 16:9, and is inferred from the prompt when omitted. response_format accepts url or b64_json.

How style consistency is expressed in the API

Style is why most teams look at this API. The documentation splits it three ways, and the mechanisms are not interchangeable.

Curated styles: the style parameter

Curated styles are reached by name — Hand-drawn, Photorealism, Vector art. When a name exists on several model lines the API resolves it to one, so pin model when the version matters. Photorealism returns raster output, Vector art returns SVG. Send neither style nor style_id and the model default applies, published as a UUID.

Custom styles: style_id and style references

style_id is where a brand style lives, and three documented routes produce one: POST /v1/styles, references attached to a generation request, whose response returns the resolved style_id, or the Styles panel’s three-dot menu, usable when you own the style or it was shared to your account.

Two exclusion rules belong in your client code. A request carrying both style_id and references is rejected, and the V4 Styles line refuses a request carrying neither. style_match then sets how literally the style is followed: precise or flexible on V4 and V4.1, regular on V2 and V3.

Holding one style across a batch

# Requires curl and jq.
BASE=https://external.api.recraft.ai/v1

# 1. Create the style once, then keep the id.
STYLE_ID=$(curl -s -X POST "${BASE}/styles" \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -F "model=recraftv4_styles" \
    -F "file1=@reference-1.png" \
    -F "file2=@reference-2.png" | jq -r .id)

# 2. Every generation in the batch carries the same style_id.
index=0
for prompt in "product hero shot, bottle on a table" "bottle on a marble ledge, morning light"; do
  curl -s "${BASE}/images/generations" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
      -d "{\"prompt\": \"${prompt}\", \"model\": \"recraftv4_styles\", \"style_id\": \"${STYLE_ID}\", \"style_match\": \"precise\", \"n\": 2, \"response_format\": \"url\"}" \
    | jq -r '.data[].url' | while read -r url; do
      index=$((index + 1))
      curl -sL -o "recraft-${index}.webp" "${url}"
    done
done

Build the style with model=recraftv4_styles, because a style records the model it was created for and later generations must match it. Attaching references on the generation call skips that round trip, creates the style privately, and returns its id for reuse. Creation is billed once, generation per image, and the response credits field reports the sum.

Editing, vectorizing and upscaling through the API

Editing is where the model line stops being a preference. Inpainting, outpainting and the background operations run on V3 only, text_layout is V3-only, and negative_prompt is documented for V2 and V3. On V4 and V4.1 the tuning object is partially supported, with colors and background_color named in the V4.1 reference.

The utility endpoints take an image instead of a prompt and are line-agnostic: /v1/images/vectorize returns a vector graphic, /v1/images/removeBackground a cutout, and the crisp and creative upscalers differ in whether content is preserved or regenerated. The studio walkthrough covers the same operations by hand, and our Nano Banana notes and GPT Image notes cover the raster-only route.

What the documentation does not publish

The reference is detailed about fields and silent about operations. None of these has a published figure:

• Rate limits, concurrency ceilings and throughput guarantees per endpoint.
• Token lifetime, rotation and revocation policy.
• Per-endpoint latency, and any timeout the gateway enforces.
• SLA numbers, Enterprise included.
• Whether generation is synchronous: the examples read the result straight from the response and no operation id appears anywhere, but the reference never says so outright.
• How API units are bought on a given plan, beyond the exchange rate and the positive-balance rule.
• The methodology behind the V4 Styles benchmark, which the vendor says is available on request.

Third-party gateways that resell Recraft access are not official channels. Their prices and capability claims are theirs, and we do not reproduce them here.

API units and what one request costs

The pricing page publishes one exchange rate, USD $1.00 = 1,000 API units, and charges per image, per variant. Packages are prepaid, non-cancellable, non-refundable and never expire.

Edits are cheaper: vectorization and background removal at $0.01, crisp upscale at $0.004, erase region at $0.002, prompt enhancement at $0.01, remix at $0.04, and a one-off $0.005 to create a style. Creative upscale is the outlier at $0.25, and a vector batch costs roughly double its raster equivalent.

Frequently asked questions

Is the Recraft API official? Yes — documented on Recraft’s own domain, with Bearer authentication, an endpoints reference, a Swagger UI on the API host, and per-image prices in API units.

Where do I get a token? At app.recraft.ai/profile/api. The documented prerequisite is a positive API units balance, shared by every token you create.

How do I hold one style across many images? Create it through /v1/styles and send the returned style_id with every generation, or attach references and reuse the style_id the response resolves. Sending both is rejected.

Which model should I default to? recraftv4_1 is the documented default. Move to V3 for inpainting, outpainting, background work or text placed at exact positions — the docs mark those as V3-only.

Do I need to poll for a result? Nothing documents an operation id or a polling step, and the official examples read the result directly. Per-request latency is unpublished, so set your own client timeout.

Fund a unit balance, keep the model id in configuration, and choose between a curated name and a style_id before writing the worker. Those three decisions cover most of what surprises a first Recraft integration.

Published

Sep 13, 2026

Information verified

Sep 13, 2026

By

AI Tool Blog Editorial Team