Recraft V4.1 API の使い方？5分で配色指定の画像生成を動かす

TL;DR

• Recraft V4.1 シリーズはパラメータが完全に一致する一対のテキストto画像モデルです：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」、暖かなテラコッタとクリーム色の配色、コーヒー豆 1 粒のイラスト、十分な余白、スイスグリッドのレイアウト。サイズは portrait_4_3 を選択。）

recraft-v4.1/text-to-image、portrait_4_3、本文のサンプル画像は 896×1216、$0.05。

このプロンプトで生成 →

2つのモデルの選び方

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
1枚あたり	$0.01	$0.05
位置づけ	高速な試し描き、方向性の選定	ディテール豊かな最終稿
パラメータ	完全に一致（prompt / image_size / colors / background_color）	左に同じ
適する用途	バッチ探索、SNS 用画像、草稿ラウンド	納品稿、ブランド素材

2つのモデルは同じパイプラインです：Flash で 10 の方向性を $0.10 で出し、選んだものを model だけ変えて再実行し V4.1 の最終稿を $0.05、1 セット $0.15。逆にラフだけ出すなら全行程 Flash で、1,000 枚でも $10.00 です。シーン別のプロンプト選びはプロンプト大全を参照。

2つの始め方ルート

ブラウザで3ステップ：モデルページを開く → プロンプトを貼り付け、サイズを選択 → 生成をクリック、V4.1 は 1 枚 $0.05。（colors と background_color は API 経由。）初回はまずブラウザで 1 枚試し、スタイルが想定どおりか確認してからコードを書くのがおすすめです。

API で3ステップ：POST /v1/tasks で送信 → taskId を取得 → GET /v1/tasks/<taskId> で success を確認してダウンロード。

curl：最初の1枚（ブランド配色付き）

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 の事例の実際のパラメータです：濃紺、オレンジ、麦色の3色パレットに生成り色の下地。最終稿にするには 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")

パラメータ表（2つのモデルで一致）

フィールド	必須	値	説明
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 の 3 キーすべて必須、各 0–255、キーの追加は不可。リクエスト本文に表外のフィールドがあると直接 400 になります。

遭遇するエラー（API 原文）

したこと	返却
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 オブジェクトにキーを1つ余計に送った	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 を変えるだけ：他のパラメータはそのまま保持し、構図の考え方をそのまま再利用。

よくある質問

2つのモデルのパラメータは同じですか？

完全に同じです。model フィールドを変えるだけで、コードの変更はゼロです。

colors パラメータはどこで設定しますか？

API 経由のみです。Playground では colors と background_color の2つのパラメータは未提供です。

colors で指定した色だけになることは保証されますか？

いいえ。強い誘導であり、画面をできるだけその色に収めますが、ハードな固定ではありません。

一度に何枚出せますか？

一度に 1 枚です。複数枚はタスクを複数送信するかキューに並べます。

$10 で何枚出せますか？

Flash は $0.01 で 1 枚、$10 で 1,000 枚です。失敗時は課金されません。

次のステップ：NORTH BEAN のプロンプトを持ってモデルページで1枚生成し、ブランドカラーを合わせたいときは colors を API リクエストに追加；シーンテンプレートはプロンプト大全を参照。