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. 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

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)

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)

(Taken from the Flash validator record; V4.1 shares the same structure.) 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

• Yes, both models share identical parameters — change only model.
• Yes, colors is API-only; Playground doesn't expose it.
• No, colors doesn't guarantee exclusive use: it's strong guidance, not a hard clamp.
• Yes, one image per call; submit more tasks for more images.
• Yes, $10 goes far: at $0.01 per Flash image, $10 buys 1,000 drafts.

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