Recraft V4.1 API 怎么用？5 分钟跑通配色出图

TL;DR

• Recraft V4.1 系列是参数完全一致的一对文生图模型：recraft-v4.1/text-to-image 出细节更足的终稿（$0.05/张），recraft-v4.1-flash/text-to-image 快速试稿（$0.01/张，完整价格见价格页），只差一个 model 字段。打开模型页就能试，新用户注册送 200 积分。
• 特色是品牌配色：colors 传一组 RGB，画面尽量落在这组颜色里（Playground 暂不提供，走 API）。
• 调用走 HiAPI /v1/tasks 接口：提交任务拿 taskId，再查询结果，成功后从 output[0].url 下载。

它能做什么

• 摄影、插画、海报都出：写实产品图、扁平矢量插画、带标题的海报，一句描述直达。
• 配色可控：colors 指定调色板、background_color 指定底色，做品牌物料时贴住 VI。
• 6 种尺寸预设：square_hd（默认）、square、portrait_4_3、portrait_16_9、landscape_4_3、landscape_16_9，无自定义宽高。
• Flash 试稿 + V4.1 定稿：参数一样、只换 model，10 张试稿加 1 张定稿 $0.15。

下面是 V4.1 的真实成品：

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

（中文意思：极简风精品咖啡品牌海报，巨大的粗体无衬线标题 "NORTH BEAN"，暖赤陶与奶油色配色，单颗咖啡豆插画，大量留白，瑞士网格版式。尺寸选 portrait_4_3。）

recraft-v4.1/text-to-image，portrait_4_3，本文示例图 896×1216，$0.05。

用这个提示词生成 →

两个模型怎么选

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
每张	$0.01	$0.05
定位	快速试稿、挑方向	细节更足的终稿
参数	完全一致（prompt / image_size / colors / background_color）	同左
适合	批量探索、社媒配图、草稿轮	交付稿、品牌物料

两个模型同一条流水线：Flash 出 10 个方向 $0.10，选中的那条换 model 重跑成 V4.1 终稿 $0.05，一套 $0.15。反过来只出草图时全程 Flash，1,000 张也只要 $10.00。按场景挑提示词看提示词大全。

两条上手路线

浏览器 3 步：打开模型页 → 粘贴提示词、选尺寸 → 点生成，V4.1 一张 $0.05。（colors 和 background_color 要走 API。）第一次建议先在浏览器跑一张，确认风格合预期再写代码。

API 3 步：POST /v1/tasks 提交 → 拿 taskId → GET /v1/tasks/<taskId> 查到 success 后下载。

curl：第一张（带品牌配色）

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}
  }
}'

这条用的是 Flash 案例的真实参数：深蓝、橙、麦色三色调色板加米白底色。出终稿把 model 换成 recraft-v4.1/text-to-image，其余不动。

Python：提交、轮询、下载

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"]   # 临时地址，尽快下载保存
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

参数表（两个模型一致）

字段	必填	取值	说明
prompt	是	1–10000 字符	画面描述
image_size	否	square_hd（默认）/ square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	6 种预设，无自定义宽高
colors	否	RGB 对象数组，各通道 0–255	调色板强引导：画面尽量落在该组颜色；Playground 暂不提供
background_color	否	单个 RGB 对象	底色；Playground 暂不提供

每个 RGB 对象 r/g/b 三键都必填、各 0–255、不能多键。请求体里出现表外字段会直接 400。

你会遇到的报错（接口原文）

你做了什么	返回
没传 prompt	400 invalid input: prompt: missing required field "prompt"
image_size 传宽高对象	400 invalid input: image_size: got object, want string
colors 某通道传 256	400 invalid input: colors.0.r: maximum: got 256, want 255
colors 少了 b 键	400 invalid input: colors.0.b: missing required field "b"
colors 传成字符串	400 invalid input: colors: got string, want array
RGB 对象多传一个键	400 invalid input: colors.0: additional properties 'a' not allowed
余额不足	402 insufficient account balance; top up and retry
同一个 Idempotency-Key 重复提交返回 409 或 422，换新 key 再试。

上线前注意

• 回调：请求体顶层传 "callback": {"url": "https://..."}，终态自动通知。
• 及时转存：output[0].url 是临时地址，拿到就下载存进自己的存储，别把它当永久链接用。
• 配色是引导不是锁定：提示词里写了和 colors 冲突的颜色时，结果可能混合两者；要严格贴色就别在提示词里写别的颜色。
• Flash→V4.1 只换 model：其余参数原样保留，构图思路直接复用。

常见问题

两个模型的参数一样吗？

完全一样。只换 model 字段，代码零改动。

colors 参数在哪设置？

只能走 API。Playground 暂不提供 colors 和 background_color 这两个参数。

colors 能保证只用指定的颜色吗？

不能。它是强引导，画面尽量落在该组色里，但不是硬性锁定。

一次能出几张？

一次 1 张。要多张多提交任务或排队。

$10 能出多少张？

Flash $0.01 一张，$10 出 1,000 张。失败不扣费。

下一步：拿 NORTH BEAN 提示词去模型页出一张，需要贴品牌色时把 colors 加进 API 请求；场景模板看提示词大全。