How to Use Recraft V4.1 API: On-Brand Images in 5 Minutes

TL;DR

• The Recraft V4.1 family is a pair of text-to-image models with identical parameters: recraft-v4.1/text-to-image for detail-rich finals ($0.05/image) and recraft-v4.1-flash/text-to-image for fast drafts ($0.01/image) — the only difference is the model field — full tiers on the pricing page. Try it on the model page; new accounts get 200 free credits.
• The signature feature is brand colors: pass a set of RGB values in colors and the image leans into that palette (Playground doesn't expose it — API only).
• Everything runs on HiAPI /v1/tasks: submit for a taskId, poll, download from output[0].url.

What it does

• Photos, illustrations, and posters from one description: realistic product shots, flat vector art, lettered posters.
• Palette control: colors sets the palette and background_color the backdrop — on-brand assets without prompt wrangling.
• Six size presets: square_hd (default), square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9; no custom sizes.
• Flash drafts + V4.1 finals: identical parameters, change only model — 10 drafts plus 1 final is $0.15.

Here's a real V4.1 output:

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

recraft-v4.1/text-to-image, portrait_4_3, sample image 896×1216, $0.05.

Try this prompt →

Two models: which to use

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
Per image	$0.01	$0.05
Role	Fast drafts, direction-finding	Detail-rich finals
Parameters	Identical (prompt / image_size / colors / background_color)	Same
Best for	Volume exploration, social art, draft rounds	Deliverables, brand assets

One pipeline: generate 10 directions on Flash for $0.10, then rerun the keeper as V4.1 for $0.05 — change only model. Scene templates live in the prompt guide.

Two ways to start

Browser, 3 steps: open the model page → paste the prompt, pick a size → generate. (colors and background_color are API-only.)

API, 3 steps: POST /v1/tasks to submit → take the taskId → poll to success.

curl: your first image (with brand colors)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

This is the real parameter set from a Flash sample: navy, orange, and wheat plus a cream backdrop. For the final, switch model to recraft-v4.1/text-to-image and keep everything else.

Python: submit, poll, download

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "recraft-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # temporary URL — download promptly
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Parameters (identical for both models)

Field	Required	Values	Notes
prompt	yes	1–10,000 chars	The frame you want
image_size	no	square_hd (default) / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	Six presets, no custom sizes
colors	no	array of RGB objects, channels 0–255	Palette guidance: the image leans into these; not in Playground
background_color	no	one RGB object	Backdrop; not in Playground

Every RGB object requires r/g/b, each 0–255, no extra keys. Any field outside the table returns a 400.

Errors you'll actually hit (verbatim)

What you did	Response
Omitted prompt	400 invalid input: prompt: missing required field "prompt"
Sent a size object	400 invalid input: image_size: got object, want string
Sent a color channel of 256	400 invalid input: colors.0.r: maximum: got 256, want 255
Missing the b key	400 invalid input: colors.0.b: missing required field "b"
Sent colors as a string	400 invalid input: colors: got string, want array
Extra key in an RGB object	400 invalid input: colors.0: additional properties 'a' not allowed
Out of credits	402 insufficient account balance; top up and retry
Re-submitting the same Idempotency-Key returns 409 or 422; use a fresh key.

Before you ship

• Callbacks: pass "callback": {"url": "https://..."} at the request top level.
• Persist outputs: output[0].url is temporary — download it right away.
• Colors guide, they don't lock: a prompt that names conflicting colors may blend with the palette; keep color words out of the prompt when the palette must hold.
• Flash → V4.1 is a model swap: keep every other parameter and reuse the composition.

FAQ

Do the two models share the same parameters?

Yes. Change only model — everything else is identical.

Where do I set colors?

API only. Playground doesn't expose colors or background_color.

Does colors guarantee exclusive use of the palette?

No. It's strong guidance — the image leans into the palette but isn't hard-clamped to it.

How many images per call?

One. Submit more tasks for more images.

How far does $10 go?

At $0.01 per Flash image, $10 buys 1,000 drafts. Failed tasks are free.

Next: take the NORTH BEAN prompt and generate a poster, add your brand palette via the API, and browse the prompt guide for scenes.