mcpField
R
recraft-image-design

recraft-image-design

github.com/calesthioデザイン・UI219108 回インストール15 週間前に更新
リポジトリ

recraft-image-design について

Recraftの画像APIで、ラスター画像やSVGを作成・変換する制作スキルです。デザインチームが互換性のあるモデルと操作を選び、入力を検証し、納品前に出力ファイルを確認できます。

主な機能

  1. 01ラスター画像とSVGの生成
  2. 02モデルと操作の選択
  3. 03画像の編集と変換
  4. 04ベクター化と背景除去
  5. 05納品前のアセット検証

活用シーン

  1. 01ラスター案や編集可能なSVGの作成
  2. 02提供画像の編集や拡張
  3. 03納品用画像アセットの準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/calesthio/generative-media-skills --skill recraft-image-design

インストール後、Claude Code で/recraft-image-designを入力して読み込まれたか確認します。

同梱ファイルEVAL.md

詳細

Recraft の画像デザイン

Recraft は汎用的なプロンプト入力欄ではなく、デザイン制作システムとして使用してください。必要な出力仕様に基づいてモデルと操作を選び、ドキュメントに記載された API 呼び出しのみを行い、返されたアセットをすぐに保存し、納品前に実際のラスター画像または SVG を確認してください。

根拠ラベルと情報の鮮度

ラベルは文字どおりに解釈してください。

  • Documented — Recraft の公式 API リファレンス、OpenAPI ドキュメント、モデルページ、法的情報ページ、または信頼性に関するページに記載されています。
  • Inference — ドキュメントに記載された動作から導かれる結論ですが、Recraft が保証しているものではありません。
  • Production heuristic — 実務上のワークフローに関する推奨事項です。現在のアカウントと依頼内容でテストしてください。

このスキルに記載されている変動する API 情報は、2026-07-09 に確認済みです。高額な実行や規制対象の実行の前に、モデル ID、互換性、料金、制限、保持期間、利用規約を再確認してください。優先すべき契約内容は、人間が読める API ガイドです。公式の Swagger 仕様には、ガイドで説明されていないエイリアスやフィールドが追加で含まれている場合があります。小規模な検証リクエストを行わずに、それらに依存しないでください。

制作仕様を定める

API を呼び出す前に、次の項目を記録してください。

  1. 納品物：ラスター画像か編集可能な SVG か。
  2. 目標とするアスペクト比／サイズと最終用途の解像度。
  3. 必ず表示する必要がある正確な文言（該当する場合）。
  4. ブランドパレット、使用禁止色、スタイルの参考資料。
  5. 編集時に変更してはならないもの。
  6. 参考資料、人物、マーク、文言に関する権利／同意の状況。
  7. 商用利用、出所／開示、プライバシー、保持に関する要件。
  8. 探索予算と受け入れ基準。

後続ツールが実際のパスを必要とする場合は、ベクトルモデルを指定してください。ベクターアート風に見えるだけのラスター画像は、SVG の代わりにはなりません。

現行モデルを選択する

Documented、2026-07-09 確認済み： POST /v1/images/generations のデフォルトは recraftv4_1 です。公開ガイドでは、次の独自モデル ID が使用できます。

ファミリーラスターベクター用途
V4.1 expressive、standardrecraftv4_1recraftv4_1_vectorコンセプト制作、洗練されたアートディレクション、タイポグラフィ、イラスト、一般的な制作における現行のデフォルト
V4.1 expressive、Prorecraftv4_1_prorecraftv4_1_pro_vector同じラインで、約 4 MP／より大きな出力サイズ。印刷や細部の多い制作向け
V4.1 Utility、standardrecraftv4_1_utilityrecraftv4_1_utility_vector商品画像やモックアップ用素材など、よりクリーンでフラット、正面向きで予測可能な制作
V4.1 Utility、Prorecraftv4_1_utility_prorecraftv4_1_utility_pro_vector出力サイズを大きくした Utility の動作
V4recraftv4recraftv4_vector以前のデザイン重視の生成ファミリー
V4 Prorecraftv4_prorecraftv4_pro_vector以前の高解像度ファミリー
V3recraftv3recraftv3_vector厳選／カスタムスタイル、ローカライズされた編集ルート、テキストレイアウト、ネガティブプロンプト、芸術性の制御が必要な場合に使用
V2recraftv2recraftv2_vectorV2 のみに存在するレガシースタイル／エフェクト向け

Documented： V4.1 は 2026 年 5 月中旬、V4 は 2026 年 2 月、V3 は 2024 年 10 月、V2 は 2024 年 2 月にリリースされました。Recraft によると、独自モデルの 16 種すべてが API 経由で引き続き利用できます。確認時点では、公式の提供終了日や正式なサポート期間は公開されていません。

Production heuristic： 低コストで方向性を探るには V4.1 standard から始めます。承認された構図のみを Pro に移行してください。ドラマ性より予測しやすさが重視される依頼には Utility を選びます。V3 の制御機能が必須要件である場合は、ドキュメントにない V4.1 のフィールドで再現しようとせず、V3 を使い続けてください。

重要な互換性の境界
  • ドキュメント記載あり： V4 および V4.1 ファミリーは、人が読める互換性テーブルにおいて、キュレーション済みの style、style_id、カスタムスタイルの作成、negative_prompt、V3 の text_layout、artistic_level をサポートしていません。ビジュアルスタイルはプロンプトに含め、サポートされている色の制御を使用してください。
  • ドキュメント記載あり： V2/V3 は名前付きスタイルをサポートしています。API で作成したカスタムスタイルは V3/V3 Vector 用です。スタイルは互換性のあるモデルで再利用する必要があります。style と style_id は同時に指定できません。
  • ドキュメント上の矛盾： 現在の画像から画像へのエンドポイントの説明文では V3 と V4 が記載されている一方、パラメータのモデル一覧には V4.1 のラスター／ベクターバリアントが含まれています。V4.1 の画像から画像への処理は、ドキュメントに記載されているものの矛盾があるものとして扱い、本番利用前に対象アカウント／契約で確認するか、予算を確保した検証リクエストで確認してください。ローカライズされた inpaint、outpaint、replaceBackground、generateBackground は、V3/V3 Vector のみがドキュメントに記載されています。
  • ドキュメント上の曖昧さ： 古い V4 モデルページではプロンプトによる編集はサポートされていないと記載されており、現在のエンドポイントガイド自体にある説明文とパラメータ一覧の不一致を裏付けています。画像から画像への処理に関するサポートの結論を、ローカライズされた編集ルートにまで拡張しないでください。
  • ドキュメント上の境界： Recraft Studio に表示されるサードパーティモデルは、社内の Swagger 列挙型に追加の名前が公開されている場合でも、公開 Recraft API の対象ではありません。

API の契約

公式の本番ホストのみを使用してください。

https://external.api.recraft.ai

保護されたすべてのリクエストで、次を使用して認証してください。

Authorization: Bearer $RECRAFT_API_TOKEN

トークンをアセット URL、ユーザー提供の URL、リダイレクト先、ロギングサービス、または external.api.recraft.ai 以外のホストに送信しないでください。環境変数に保存してください。出力しないでください。

主要なルート

ドキュメント記載あり、2026-07-09 に検証済み： 以下のすべてのルートは https://external.api.recraft.ai/v1 配下にあります。

メソッドとパス目的レスポンス形式
POST /images/generationsラスターまたはベクターのテキストから画像生成{"created":...,"credits":...,"data":[Image...]}
POST /images/generations/raster同じリクエスト本文。ラスターのモデル／スタイルを強制同じ
POST /images/generations/vector同じリクエスト本文。ベクターのモデル／スタイルを強制同じ
POST /styles画像／ソーススタイルから V3 カスタムスタイルを作成スタイルオブジェクトと credits
POST /images/imageToImageプロンプトで誘導する画像のバリエーション／変換生成レスポンス
POST /images/inpaint白いマスク領域を塗りつぶす生成レスポンス
POST /images/outpaintキャンバスを拡張する生成レスポンス
POST /images/replaceBackground背景を検出して置き換える生成レスポンス
POST /images/generateBackground指定された背景マスクを塗りつぶす生成レスポンス
POST /images/vectorizeラスターを SVG に変換{"created":...,"credits":...,"image":Image}
POST /images/removeBackgroundラスター／SVG の背景を削除画像処理レスポンス
POST /images/crispUpscale構造を保持したラスターのアップスケール画像処理レスポンス
POST /images/creativeUpscaleディテール／顔を再生成してアップスケール画像処理レスポンス
POST /images/eraseRegion白いマスク領域を消去画像処理レスポンス
POST /images/variateImageプロンプトなしで、指定サイズにリミックス生成レスポンス
POST /images/explore多様な探索セットを生成生成レスポンス
POST /images/explore/similarExplore の image_id を起点に続行生成レスポンス
POST /prompts/enhanceプロンプトを拡張。最大 2,000 文字{"enhanced_prompt":...,"credits":...}
GET /users/meアカウントの識別情報とユニット残高credits を含むユーザーオブジェクト

公式 Swagger には、スタイル／モデルの取得ルートとスタイル削除ルートも記載されています。人向けのガイドではすべてのスキーマが詳しく説明されていないため、本番利用前に機能の有無を確認するものとして、GET /styles、GET /styles/basic、GET /styles/{style_id}、DELETE /styles/{style_id}、GET /models を Swagger に記載されたルートとして扱ってください。

生成リクエスト

/images/generations の JSON ボディでは、次の項目を使用します。

項目仕様
prompt必須の文字列。V4/V4.1 では最大 10,000 文字、V2/V3 では最大 1,000 文字
model上記の公開モデル ID のいずれか。デフォルトは recraftv4_1
n整数 1..6。画像ごとに課金
sizeサポート対象の WxH またはアスペクト比 w:h。省略した場合はプロンプトから選択
random_seed任意の符号なし整数。再試行に備えて記録してください
response_formaturl（デフォルト）または b64_json
style / style_idV2/V3 のみ。両方を同時に指定しないでください
negative_promptV2/V3 のみ
text_layoutV3/V3 Vector のみ
controlsドキュメントに記載されたすべてのファミリーでパレット／背景に対応。artistic_level と no_text は V3 のみ

Swagger には記載されていますが、ガイドでの説明は限られています： ラスター形式のレスポンスでは、image_format に png または webp を指定します。ベクターモデルは SVG を返します。Studio のエクスポート形式（JPG、PDF、TIFF、Lottie など）が有効な API の image_format 値だと想定しないでください。

Image には、image_id、url または b64_json、revised_prompt、および任意の機能データが含まれる場合があります。デコードまたはダウンロードする前に、想定されるペイロードフィールドが存在することを検証してください。

サイズ

ドキュメントに記載： 各ファミリーで受け付けるアスペクト比は、1:1、2:1、1:2、3:2、2:3、4:3、3:4、5:4、4:5、6:10、14:10、10:14、16:9、および 9:16 です。

標準的な V4/V4.1 ラスターの例には、1024x1024、1536x768、768x1536、1280x832、832x1280、1216x896、896x1216、1152x896、896x1152、832x1344、1280x896、896x1280、1344x768、および 768x1344 があります。対応する Pro の寸法は、各辺が 2 倍になり、2048x2048、3072x1536、2688x1536 などになります。

V2/V3 ラスターでは、別の明示的なサイズ表を使用します。たとえば、1024x1024、2048x1024、1024x2048、1536x1024、1024x1536、1820x1024、および 1024x1820 です。ベクターモデルで受け付けるのは、ピクセルサイズが保証される値ではなく、ドキュメントに記載されたアスペクト比トークンです。任意の寸法を独自に作成せず、付録を再確認してください。

画像入力とマスク

画像を受け取るエンドポイントでは、次のいずれかを使用します。

  • image、mask、または file を含む multipart/form-data。または
  • 対応する image_url と mask_url を含む application/json。公開 URL または data:image/...;base64,... 形式のデータ URL を使用します。

現在の変換ルートでは、入力画像は通常 PNG/JPG/WEBP または SVG で、サイズは 10 MB 以下、16 MP 以下、最大寸法は 4096 px、最小寸法は 256 px です。操作ごとの制約を確認してください。消去およびユーティリティのエンドポイントでは制約が異なります。

インペイント／背景生成用マスクの場合：

  • 元画像と寸法を完全に一致させてください。
  • グレースケールの PNG/JPG/WEBP を使用してください。
  • 変更する領域には純白（255）、そのまま残す領域には純黒（0）を使用してください。
  • アップロード前に、アンチエイリアスや意図しないグレーのピクセルを除去してください。
変換リクエスト

/images/imageToImage では、image/image_url、prompt、および [0,1] の範囲の strength が必須です。0 はほぼ同一、1 は類似性が最小であることを意味します。また、n 1..6、モデル、シード、レスポンス形式、およびモデルに対応する制御項目も指定できます。

/images/inpaint では、画像、マスク、およびプロンプトが必須です。/images/generateBackground も同じ入力形式を使用します。/images/replaceBackground では、画像とプロンプトが必須です。

/images/outpaint では、画像とプロンプトに加えて、次のいずれか 1 つ以上が必要です。

  • size。または
  • 0..4096 の範囲で指定する expand_left、expand_right、expand_top、expand_bottom のいずれか 1 つ以上。または
  • [0,100) の範囲の zoom_out_percentage。

size と expand_* を同時に指定しないでください。zoom_out_percentage は、どちらと併用してもかまいません。最終寸法は各辺 4096 px 以下にしてください。

/images/variateImage では、画像と size が必須です。n 1..6、モデル、シード、レスポンス形式を指定できますが、プロンプトは指定できません。

ベクター化と背景の削除

/images/vectorize は file または image_url を受け付け、SVG 画像を返します。Swagger には記載されていますが、ガイドでは詳しく説明されていないベクター化オプションには、svg_compression、limit_num_shapes、max_num_shapes、色数の削減、グラデーションの返却、シェイプの重ね順、小さなシェイプのフィルタリング、strict_color_palette があります。ガイドではすべての列挙値と相互作用が公開されていないため、現行の Swagger スキーマを低コストのテストで検証していない限り、これらの指定は省略してください。

/images/removeBackground はラスター形式または SVG を受け付けます。ラスター形式の入力にはラスター形式、SVG の入力には SVG を返します。背景の削除後も SVG 形式が保たれるからといって、編集しやすいトポロジーが得られると約束しないでください。

同期、バッチ、エラーの動作
  • 公開仕様に記載あり： エンドポイントの呼び出しは、完了したレスポンスを同期的に返します。n=1..6 が、複数画像リクエストとして記載されている方法です。
  • マーケティング上の説明のみ： Recraft の API ランディングページでは、非同期ジョブ、バッチ生成、優先推論が宣伝されています。検証時点では、公開エンドポイントガイドにも公開済み Swagger にも、ジョブの送信、ポーリング、キャンセル、Webhook、署名、優先度のスキーマはありませんでした。これらを独自に作り出さないでください。実装前に、Recraft からエンタープライズ契約を入手してください。
  • 公開仕様に記載されたレート： 付録ではユーザーごとに毎分 100 画像、毎秒 5 リクエストとされています。API 利用規約では別途、毎分 100 リクエストと記載されています。画像数とリクエスト数の両方を制限し、アカウントごとに調整される可能性を考慮してください。
  • 未公開の詳細： 公開リファレンスには、安定したエラー本文や完全なステータスコード一覧が記載されていません。2xx 以外はすべて失敗として扱い、ステータス、レスポンス本文、レスポンスヘッダー、X-Recraft-Requestid を記録してください。Retry-After がある場合はそれに従ってください。429 と、リクエスト送信前に発生したことが確認できる接続失敗は、上限のあるバックオフとジッターを使って再試行してください。読み取りタイムアウト、送信後のタイムアウト、送信後の接続切断、5xx の結果は、課金対象となる可能性がある、または結果が曖昧なものとして扱ってください。再送信する前に、ローカルの台帳、または Recraft のサポートや契約を通じて照合し、保留にしてください。検証、認証、支払いに関する失敗は、安易に再試行しないでください。
  • ジョブ ID、プロンプトのハッシュ、モデル、シード、予定件数をキーにした冪等性台帳を使用してください。Recraft は冪等性キーのヘッダーを文書化していないため、送信後のタイムアウトは、課金対象となる結果不明の状態を示している可能性があります。

デザインの直接制御

アートディレクションの仕様としてのプロンプト

V4/V4.1 では、次の順序で一貫性のある仕様を 1 つ作成してください。

  1. 成果物と主題。
  2. 構図と階層。
  3. 素材、照明、レンダリングの表現。
  4. 引用符で囲んだ正確なテキストとその役割。
  5. 配色と背景との関係。
  6. 肯定形で示す制約。
  7. 想定用途と、トリミングしても重要な要素が切れない領域。

類義語を長く羅列するのは避けてください。「中央に 1 つだけ配置したロゴ一式」「見出しは上部 3 分の 1 を占める」「3 つのオブジェクトを等間隔に配置」「グラデーションなしのベタ塗り」「パッケージに正対したカメラ」のように、要素間の関係を指定してください。

配色とブランドの一貫性

仕様に記載あり： controls.colors は、必須の rgb: [r,g,b] と、任意の weight（0..1）を含むオブジェクトの配列です。色のウェイトの合計は 1 を超えてはなりません。controls.background_color でも、同じカラーオブジェクトを使用します。これらの設定は優先指定であり、ピクセル単位の完全一致を保証するものではありません。

本番環境でのヒューリスティック： 承認済みのブランドカラーの HEX 値をコードで RGB に変換し、必要な場合にのみ主要色に大きなウェイトを割り当て、未割り当てのウェイトはニュートラルカラー用に確保してください。生成後に、サンプリングした出力色を検証してください。ロゴや規制対象の色を厳密に一致させる必要がある場合は、周囲のデザインを生成し、承認済みのベクター、ロゴ、色を決定論的なデザインソフトウェアで合成してください。

スタイルとサブスタイル

ドキュメントに記載： V3 の厳選スタイルには、Photorealism、Illustration、Recraft V3 Raw などのラスターカテゴリと、Vector art、Line art、Engraving などのベクターカテゴリがあります。V2 には、追加のレガシーエフェクトがあります。名称や利用可否は変更される可能性があるため、最新のスタイル一覧を使用してください。

Swagger には記載、ガイドでは詳細が限定的： リクエストで substyle を指定でき、OpenAPI には多数の列挙値があります。人間向けの API ガイドでは、すべての生の列挙値とモデルの組み合わせを保証するのではなく、名前付きスタイルとして整理されています。一覧に記載された style またはアクセス可能な style_id を優先してください。生の substyle を使うのは、事前に調査し、検証リクエストを送信した後にしてください。

V3 のカスタムスタイルを作成するには、POST /styles に、ドキュメントに記載されたベースタイプ（any、realistic_image、digital_illustration、vector_illustration、icon、logo_raster）のいずれかと、最大5点の PNG/JPG/WEBP 参照画像を指定します。人間向けのガイドでは、参照画像の合計サイズは5 MBまで、各アップロードは現在のアップロード上限までとされています。また、任意項目として、モデル、画像の重み、ソーススタイル ID／重み、プロンプト、および PaletteMatch または MaxWeight の mix_policy も記載されています。

アップロードおよび加工する権利を有する参照画像のみを使用してください。カスタムスタイルは、保護された作品をコピーしたり、存命のアーティストになりすましたりするための許可にはなりません。

テキストとレイアウト

V4/V4.1 では、正確な短い文言を引用符で囲み、階層や配置を説明してください。長い法的文言やピクセル単位で正確なタイポグラフィが必要な場合は、まずビジュアルの土台を生成し、その後、決定論的な方法で文字を組版してください。

V3 の text_layout では、1つの単語につき1つのオブジェクトを指定します。

{
  "text": "RECRAFT",
  "bbox": [[0.20, 0.40], [0.80, 0.40], [0.80, 0.56], [0.20, 0.56]]
}

バウンディングボックスは、相対座標で表す4つの [x,y] 点で構成されます。(0,0) が左上、(1,1) が右下です。座標はこの範囲を超えてもよく、その場合はクロップされます。API で使用可能な文字セットは制限されています。送信する前に、すべての文字を検証してください。1つの text 項目内にスペースを入れないでください。単語ごとに分けて指定します。

探索と再現性

random_seed を使用して生成試行を再現可能にします。ただし、バックエンドの変更をまたいで、シードやモデルのラベルがアーカイブ上の保証になるとは考えないでください。出力バイト列、リクエスト JSON、モデル ID、シード、時刻、レスポンス ID、クレジット数、コンテンツハッシュを保存してください。

/images/explore は、対応する V4/V4.1 の表現力重視モデルおよび Pro モデルでのみ使用してください。ビジュアル探索用の画像セットが返されます。/images/explore/similar には、Explore から取得した image_id と、1..5 の類似度が必要です。探索では、一時的なサーバー側の成果物が作成される場合があります。保持期間を確認せずに、機密情報に使用しないでください。

本番ワークフロー

  1. 事前確認： トークン、/users/me で確認できる API ユニット残高、権利、出力タイプ、現在のモデルとの互換性、レート予算、公式ホストを確認します。
  2. 試作： 標準解像度で n=1 を生成します。リクエスト／レスポンスとアセットをすぐに保存します。
  3. 方向性の確認： 費用を増やす前に、ブリーフ、構図、文言、配色、人体表現、ブランドリスク、望ましくないコンテンツを確認します。
  4. 変数を1つずつ変更： プロンプト、モデル、シード、配色、または操作を変更します。一度にすべてを変更しないでください。変更理由を記録します。
  5. 本採用： 方向性の承認後にのみ Pro を使用し、同じアスペクト比とアートディレクションを維持します。
  6. 仕上げ： URL からすぐにダウンロードし、MIME タイプ／シグネチャと寸法を検証するか、SVG を安全に解析します。ハッシュを計算し、スキャンして、管理されたストレージに保存します。
  7. QA： 想定される表示サイズと100%表示で確認します。SVG の編集可能性、クリッピング、透明度、小さいサイズでの読みやすさをテストします。
  8. 来歴の記録： プロンプト、モデル、シード、タイムスタンプ、Recraft のリクエスト ID／画像 ID、ソースの使用許諾、編集内容、開示の判断を保持します。
ラスター画像の QA
  • 被写体の数と形状が正しいこと；
  • 照明／反射／素材に一貫性があること；
  • 必要な文言が正確で、余計なテキストがないこと；
  • 主要な要素がクリップされていないこと；クロップに耐える構図であること；
  • 意図した配色、コントラスト、透明度／背景の挙動であること；
  • 最終サイズで顔／手／製品に欠陥がないこと；
  • 実際の寸法、ファイルシグネチャ、アルファ、カラープロファイルを確認済みであること。
ベクター QA
  • スクリプト／外部参照を無効にした状態で、SVG が正しく解析されること；
  • 明示的に許可されていない限り、ラスター画像が埋め込まれていないこと；
  • パス数、グループ化、塗り、線、viewBox が適切であること；
  • 意図しないクリッピング、閉じていない継ぎ目、微小な不要要素、過剰なノードがないこと；
  • テキストが、後続の編集ニーズに応じて変換または処理されていること；
  • 単色およびグラデーションの要件を満たしていること；
  • ファビコン／アイコンサイズでも判読でき、大きなサイズでもきれいであること。

完全な例

以下はすべて例であり、必須の定型ではありません。curl、Python 3、Pillow、defusedxml、および RECRAFT_API_TOKEN という名前の環境変数が設定されていることを前提としています。

例 1 — V4.1 でブランドを統制したラスター画像を安全かつ永続的にダウンロード

意図：落ち着いたブランドパレットを使い、16:9 のキャンペーン用キービジュアルを 1 点作成します。V4.1 のスタイルはプロンプトで指定し、controls で色の傾向を指定します。

set -euo pipefail
: "${RECRAFT_API_TOKEN:?Set RECRAFT_API_TOKEN}"

curl --fail-with-body --silent --show-error \
  --connect-timeout 15 --max-time 180 --max-filesize 5000000 --remove-on-error \
  --dump-header response.headers \
  'https://external.api.recraft.ai/v1/images/generations/raster' \
  -H "Authorization: Bearer ${RECRAFT_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -o response.json \
  --data-binary @- <<'JSON'
{
  "prompt": "Editorial launch key visual for a precision ceramic travel mug, one mug centered slightly right with open copy space in the left third, camera square to product, soft directional daylight, tactile matte ceramic and brushed steel, calm premium composition, deep navy background with a restrained coral accent, no logos, no embedded words, no extra products, 16:9 crop-safe layout",
  "model": "recraftv4_1",
  "n": 1,
  "size": "16:9",
  "random_seed": 284771,
  "response_format": "url",
  "image_format": "png",
  "controls": {
    "colors": [
      {"rgb": [10, 31, 68], "weight": 0.55},
      {"rgb": [242, 101, 91], "weight": 0.20}
    ],
    "background_color": {"rgb": [10, 31, 68]}
  }
}
JSON

python - <<'PY'
import hashlib, io, json, pathlib, urllib.error, urllib.parse, urllib.request, warnings
from datetime import datetime, timezone
from PIL import Image

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

def open_https_without_auth(url, max_redirects=3):
    opener = urllib.request.build_opener(NoRedirect)
    current = url
    for _ in range(max_redirects + 1):
        parsed = urllib.parse.urlparse(current)
        if parsed.scheme != "https" or not parsed.hostname:
            raise SystemExit("Refusing non-HTTPS asset redirect")
        req = urllib.request.Request(current, headers={"User-Agent": "recraft-production-download/1"})
        try:
            return opener.open(req, timeout=120)
        except urllib.error.HTTPError as exc:
            if exc.code not in {301, 302, 303, 307, 308} or not exc.headers.get("Location"):
                raise
            current = urllib.parse.urljoin(current, exc.headers["Location"])
    raise SystemExit("Too many asset redirects")

r = json.loads(pathlib.Path("response.json").read_text(encoding="utf-8"))
item = r["data"][0]
url = item["url"]
u = urllib.parse.urlparse(url)
if u.scheme != "https" or not u.hostname:
    raise SystemExit("Refusing non-HTTPS asset URL")
with open_https_without_auth(url) as src:
    content_type = src.headers.get_content_type()
    body = src.read(50 * 1024 * 1024 + 1)
if len(body) > 50 * 1024 * 1024 or content_type != "image/png":
    raise SystemExit(f"Unexpected asset: {content_type}, {len(body)} bytes")
if not body.startswith(b"\x89PNG\r\n\x1a\n"):
    raise SystemExit("File signature does not match requested PNG")
warnings.simplefilter("error", Image.DecompressionBombWarning)
with Image.open(io.BytesIO(body)) as decoded:
    actual_size = decoded.size
    if actual_size != (1344, 768):
        raise SystemExit(f"Expected 1344x768 for standard 16:9, decoded {actual_size}")
    decoded.verify()
output = pathlib.Path("campaign-key-visual.png")
temporary = output.with_suffix(".png.tmp")
temporary.write_bytes(body)
temporary.replace(output)
pathlib.Path("campaign-key-visual.metadata.json").write_text(json.dumps({
    "submitted_request": {
        "prompt": "Editorial launch key visual for a precision ceramic travel mug, one mug centered slightly right with open copy space in the left third, camera square to product, soft directional daylight, tactile matte ceramic and brushed steel, calm premium composition, deep navy background with a restrained coral accent, no logos, no embedded words, no extra products, 16:9 crop-safe layout",
        "model": "recraftv4_1", "n": 1, "size": "16:9",
        "random_seed": 284771, "response_format": "url", "image_format": "png",
        "controls": {"colors": [{"rgb": [10, 31, 68], "weight": 0.55},
                                  {"rgb": [242, 101, 91], "weight": 0.20}],
                     "background_color": {"rgb": [10, 31, 68]}},
    },
    "response": r,
    "response_headers": pathlib.Path("response.headers").read_text(encoding="iso-8859-1"),
    "saved_utc": datetime.now(timezone.utc).isoformat(),
    "image_id": item.get("image_id"),
    "credits": r.get("credits"), "actual_size": actual_size,
    "sha256": hashlib.sha256(body).hexdigest(),
}, indent=2), encoding="utf-8")
PY

期待される結果：ネイビーを主役にしたアートディレクションで、左側にコピー用の余白がある標準解像度のラスター画像が 1 点生成されます。起こりやすい失敗：マグカップ／ロゴの幻覚、余白不足、パレットの逸脱です。Pro を使う前に、プロンプトまたはシードを調整してください。

バリエーション：承認後、モデルを recraftv4_1_pro に切り替え、アスペクト比／プロンプト／controls はそのままにして、ローカルの想定サイズのアサーションを (1344, 768) から、ドキュメントに記載された Pro の 16:9 サイズ (2688, 1536) に更新します。

例 2 — base64 レスポンスによるネイティブ SVG ロゴの探索

意図：有効期限のある URL に頼らず、編集可能なフラットなベクター形状を生成します。

set -euo pipefail
: "${RECRAFT_API_TOKEN:?Set RECRAFT_API_TOKEN}"

curl --fail-with-body --silent --show-error \
  --connect-timeout 15 --max-time 180 --max-filesize 30000000 --remove-on-error \
  --dump-header vector-response.headers \
  'https://external.api.recraft.ai/v1/images/generations/vector' \
  -H "Authorization: Bearer ${RECRAFT_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -o vector-response.json \
  -d '{
    "prompt": "Single centered symbol for a neighborhood seed library: an open seed pod forming a subtle letter S through negative space, flat vector geometry, two solid colors, bold silhouette, no gradients, no shadows, no mockup, no secondary symbols, no words, legible at 24 pixels",
    "model": "recraftv4_1_vector",
    "n": 1,
    "size": "1:1",
    "random_seed": 99214,
    "response_format": "b64_json",
    "controls": {"colors": [{"rgb": [20, 84, 63], "weight": 0.55}, {"rgb": [244, 184, 65], "weight": 0.30}]}
  }'

python - <<'PY'
import base64, hashlib, json, pathlib, re
from datetime import datetime, timezone
from defusedxml import ElementTree as ET

response_path = pathlib.Path("vector-response.json")
if response_path.stat().st_size > 30_000_000:
    raise SystemExit("Vector response exceeded transport cap")
r = json.loads(response_path.read_text(encoding="utf-8"))
raw = base64.b64decode(r["data"][0]["b64_json"], validate=True)
if len(raw) > 20 * 1024 * 1024 or b"<svg" not in raw[:4096].lower():
    raise SystemExit("Response is not a plausible SVG")
root = ET.fromstring(raw)
if root.tag.startswith("{"):
    namespace, local_root = root.tag[1:].split("}", 1)
else:
    namespace, local_root = "", root.tag
if local_root.lower() != "svg" or namespace not in {"", "http://www.w3.org/2000/svg"}:
    raise SystemExit("Root element is not SVG")
without_declaration = re.sub(br"^\s*<\?xml[^?]*\?>", b"", raw, count=1, flags=re.I)
if b"<?" in without_declaration:
    raise SystemExit("SVG contains a processing instruction")
allowed_tags = {
    "svg", "g", "defs", "title", "desc", "path", "rect", "circle", "ellipse",
    "line", "polyline", "polygon", "lineargradient", "radialgradient", "stop",
    "clippath", "mask",
}
allowed_attributes = {
    "id", "class", "viewbox", "width", "height", "x", "y", "x1", "y1", "x2", "y2",
    "cx", "cy", "r", "rx", "ry", "d", "points", "fill", "fill-opacity", "fill-rule",
    "stroke", "stroke-width", "stroke-linecap", "stroke-linejoin", "stroke-miterlimit",
    "stroke-dasharray", "stroke-dashoffset", "stroke-opacity", "opacity", "transform",
    "clip-path", "mask", "gradientunits", "gradienttransform", "spreadmethod", "offset",
    "stop-color", "stop-opacity", "preserveaspectratio", "href",
}
for element in root.iter():
    local_tag = element.tag.rsplit("}", 1)[-1].lower()
    if local_tag not in allowed_tags:
        raise SystemExit(f"SVG element is outside the passive allowlist: {local_tag}")
    for name, value in element.attrib.items():
        local_name = name.rsplit("}", 1)[-1].lower()
        lowered = value.strip().lower()
        if local_name.startswith("on") or local_name not in allowed_attributes:
            raise SystemExit(f"SVG attribute is outside the passive allowlist: {local_name}")
        if local_name == "href" and lowered and not lowered.startswith("#"):
            raise SystemExit("SVG contains an external/data reference")
        if "url(" in lowered and not re.search(r"url\(\s*['\"]?#", lowered):
            raise SystemExit("SVG contains a URL-based paint/reference")
        if "javascript:" in lowered or "data:" in lowered or "@import" in lowered:
            raise SystemExit("SVG contains active or embedded content")
output = pathlib.Path("seed-library-mark.svg")
temporary = output.with_suffix(".svg.tmp")
temporary.write_bytes(raw)
temporary.replace(output)
pathlib.Path("seed-library-mark.metadata.json").write_text(json.dumps({
    "submitted_request": {
        "prompt": "Single centered symbol for a neighborhood seed library: an open seed pod forming a subtle letter S through negative space, flat vector geometry, two solid colors, bold silhouette, no gradients, no shadows, no mockup, no secondary symbols, no words, legible at 24 pixels",
        "model": "recraftv4_1_vector", "n": 1, "size": "1:1",
        "random_seed": 99214, "response_format": "b64_json",
        "controls": {"colors": [{"rgb": [20, 84, 63], "weight": 0.55},
                                  {"rgb": [244, 184, 65], "weight": 0.30}]},
    },
    "response": r,
    "response_headers": pathlib.Path("vector-response.headers").read_text(encoding="iso-8859-1"),
    "saved_utc": datetime.now(timezone.utc).isoformat(),
    "image_id": r["data"][0].get("image_id"), "credits": r.get("credits"),
    "sha256": hashlib.sha256(raw).hexdigest(),
}, indent=2), encoding="utf-8")
PY

期待される結果：コンパクトな 2 色のマークを含む SVG が生成されます。起こりやすい失敗：意図しないテキストの埋め込み、過剰なノード、24 px でのシルエットの弱さです。ベクターエディターで確認して簡素化してください。生成結果から商標のクリアランスが得られたと主張しないでください。

例 3 — 厳格なマスクの意味を適用した V3 のマスク付きインペイント

意図：ラスター写真の残りの部分を維持しながら、選択した商品ラベルの領域だけを置き換えます。

入力：product.png と、ラベル部分が白、それ以外がすべて黒の、寸法が完全に一致する二値の mask.png。

set -euo pipefail
: "${RECRAFT_API_TOKEN:?Set RECRAFT_API_TOKEN}"

python - <<'PY'
import pathlib
from PIL import Image
for name in ("product.png", "mask.png"):
    path = pathlib.Path(name)
    if path.stat().st_size > 10 * 1024 * 1024:
        raise SystemExit(f"{name} exceeds 10 MB")
    with Image.open(path) as check:
        width, height = check.size
        if min(width, height) < 256 or max(width, height) > 4096 or width * height > 16_000_000:
            raise SystemExit(f"{name} is outside the documented dimension/pixel bounds")
        check.verify()
        if check.format != "PNG":
            raise SystemExit(f"{name} must actually be PNG for the declared MIME type")
with Image.open("product.png") as im, Image.open("mask.png") as mask_source:
    if mask_source.mode not in {"1", "L"}:
        raise SystemExit("The uploaded mask bytes must already be binary/grayscale")
    mask = mask_source.convert("L")
    if im.size != mask.size:
        raise SystemExit("Mask dimensions must equal source dimensions")
    if set(mask.getdata()) - {0, 255}:
        raise SystemExit("Mask must contain only pure black and white pixels")
PY

curl --fail-with-body --silent --show-error \
  --connect-timeout 15 --max-time 180 --max-filesize 70000000 --remove-on-error \
  --dump-header inpaint-response.headers \
  'https://external.api.recraft.ai/v1/images/inpaint' \
  -H "Authorization: Bearer ${RECRAFT_API_TOKEN}" \
  -F '[email protected];type=image/png' \
  -F '[email protected];type=image/png' \
  -F 'prompt=Minimal cream paper label with a small centered green leaf emblem, matching the existing bottle curvature, lighting, grain, and perspective; no readable words' \
  -F 'model=recraftv3' \
  -F 'n=1' \
  -F 'random_seed=44102' \
  -F 'response_format=b64_json' \
  -o inpaint-response.json

python - <<'PY'
import base64, hashlib, io, json, pathlib, warnings
from datetime import datetime, timezone
from PIL import Image
response_path = pathlib.Path("inpaint-response.json")
if response_path.stat().st_size > 70_000_000:
    raise SystemExit("Inpaint response exceeded transport cap")
r = json.loads(response_path.read_text(encoding="utf-8"))
raw = base64.b64decode(r["data"][0]["b64_json"], validate=True)
if len(raw) > 50 * 1024 * 1024:
    raise SystemExit("Inpaint output exceeds local 50 MiB safety limit")
if raw.startswith(b"\x89PNG\r\n\x1a\n"):
    suffix = ".png"
elif raw.startswith(b"RIFF") and raw[8:12] == b"WEBP":
    suffix = ".webp"
else:
    raise SystemExit("Unexpected inpaint output signature")
warnings.simplefilter("error", Image.DecompressionBombWarning)
with Image.open("product.png") as source:
    expected_size = source.size
with Image.open(io.BytesIO(raw)) as decoded:
    actual_size = decoded.size
    if (max(actual_size) > 4096 or actual_size[0] * actual_size[1] > 16_000_000
            or actual_size != expected_size):
        raise SystemExit(f"Unexpected inpaint dimensions: {actual_size}; expected {expected_size}")
    decoded.verify()
output = pathlib.Path("product-inpaint" + suffix)
temporary = output.with_suffix(output.suffix + ".tmp")
temporary.write_bytes(raw)
temporary.replace(output)
pathlib.Path("product-inpaint.metadata.json").write_text(json.dumps({
    "submitted_request": {
        "prompt": "Minimal cream paper label with a small centered green leaf emblem, matching the existing bottle curvature, lighting, grain, and perspective; no readable words",
        "model": "recraftv3", "n": 1, "random_seed": 44102,
        "response_format": "b64_json",
    },
    "input_sha256": {name: hashlib.sha256(pathlib.Path(name).read_bytes()).hexdigest()
                     for name in ("product.png", "mask.png")},
    "response": r,
    "response_headers": pathlib.Path("inpaint-response.headers").read_text(encoding="iso-8859-1"),
    "saved_utc": datetime.now(timezone.utc).isoformat(),
    "image_id": r["data"][0].get("image_id"), "credits": r.get("credits"),
    "actual_size": actual_size, "sha256": hashlib.sha256(raw).hexdigest(),
}, indent=2), encoding="utf-8")
PY

この例では Pillow のみを使ってマスクを検証します。期待される結果：選択したラベルが変化し、マスクされていない領域はおおむね安定したままになります。起こりやすい失敗：マスクの境目、照明の不一致、意図しないテキストです。API では二値が必須のため、グレーのマスクピクセルでぼかしを表現することはできません。選択範囲の形状を調整して再生成してください。

移行とフォールバックの方針

古い統合を V4.1 に移行する際は、次の手順に従ってください。

  1. 承認済みの V2／V3 出力とリクエストのメタデータをスナップショットに保存します；
  2. 使用中のすべてのフィールドとルートを一覧にします；
  3. 生成処理を、V3 のみで使えるスタイル、ネガティブプロンプト、テキストレイアウト、アーティスティックレベル、ローカライズ編集への依存から切り分けます；
  4. プレーンなテキストから画像への生成を、標準解像度の recraftv4_1 または Utility に移行します；
  5. スタイルの意図をプロンプトに反映し、パレットの controls は維持します；
  6. 固定したブリーフ一式を新旧モデルで実行し、構図、コピー、パレット、欠陥、コストを評価します；
  7. controls を黙って削除するのではなく、V3 のみで必要な操作には V3 の呼び出しを維持します；
  8. 解像度の向上によって承認率が実質的に高まる場合に限り、Pro に移行します；
  9. アセットマニフェストでモデルとリクエストスキーマのバージョンを管理します；
  10. 公式の変更履歴／ドキュメントを監視し、デフォルトを変更する前にテスト一式を再実行します。

ラスターをベクターに、標準解像度を Pro に、Expressive を Utility に、インペイントを画像から画像への生成に、Studio モックアップを API ルートに、黙って置き換えないでください。変更された成果物を明示し、承認を得てください。

安全性、プライバシー、権利、来歴

文書化された法的条件、2026-07-09 時点で確認済み： API の顧客は API を通じて作成されたアセットを所有し、Recraft は、コンプライアンスの遵守と、アセットを AI モデル／システム／ネットワークのトレーニングに使用することの厳格な禁止を条件として、Recraft が保有する可能性のあるあらゆる著作権を、個人利用または商用利用のために譲渡します。Recraft の API 固有の信頼に関する声明では、API の入力と出力はモデルのトレーニングに一切使用されないとされています。一方、API 利用規約では、カスタマーサポート、法令遵守、ポリシーの適用に必要な場合の取り扱いが別途認められています。この API 固有の例外は、Studio 全般のトレーニング／オプトアウト制度とは区別してください。一般的な無料プランの規則も異なります。Free Tier の Studio アセットは Recraft が所有し、公開され、個人利用のみが認められ、商用利用はできません。Studio の無料プランの条件を有料 API の出力に適用したり、その逆を行ったりしないでください。

Recraft からの所有権の譲渡は、第三者の権利確認を意味するものではありません。入力内容および利用に関する権利（著作権、商標、プライバシー、パブリシティ権、同意を含みます）については、引き続き顧客が責任を負います。欺瞞的ななりすまし、個人を特定できるデータ、虐待的／違法なコンテンツ、児童搾取、同意のない親密な画像、有害な偽情報、テロ支援、保護対象の属性を持つ人々への暴力につながる生成は行わないでください。人物、商標、規制対象の主張、政治的説得、高リスクな用途については、人間による確認および法務確認を適用してください。

文書化されたプライバシー／保持期間： 公式ページ間で完全には整合していません。API 利用規約では、Recraft はデフォルトで、配信後に API の画像／メタデータを保存しないとされています。一方、API 付録および信頼に関するドキュメントでは、生成結果は約 24 時間以内に保存・削除されるとされています。探索／反復機能ではアーティファクトが一時的に保持される場合があり、任意の保持設定によって保存期間を延長できます。保守的なルールに従って運用してください。処理および署名付きリンクの利用可能期間は最大約 24 時間と想定し、すぐにダウンロードし、Recraft の URL を非公開ストレージとして扱わず、機密性の高いワークロードを実行する前に Recraft に契約上の確認を求めてください。

文書化済み： URL の出力は、暗号署名された URL を知っている人であれば誰でも、認証なしでアクセスできます。秘密情報、未公開の機密デザイン、生体データ、不要な個人データをプロンプト／画像に含めないでください。リンクの露出が許容できない場合は b64_json を優先してください。ただし、プロバイダーが引き続きコンテンツを処理する点には留意してください。

文書化された来歴に関する条件： Recraft は、機械可読メタデータ、ウォーターマーク、または来歴情報を埋め込む場合があります。法律で明示的に認められている場合を除き、Recraft が付与した来歴情報を削除または改変しないでください。法律で義務付けられる AI の開示については、ユーザーが責任を負います。Recraft は、すべての API 出力で C2PA が使用されることを公に保証していません。実際のアセットを確認し、独自の来歴記録を維持してください。

コストとアクセスの概要

**文書化された API 料金、2026-07-09 確認済み：**API ユニットは 1 USD $1 あたり 1,000 ユニットで前払いし、有効期限はありません。パッケージはキャンセル不可・返金不可です。現在の出力ごとの料金は以下のとおりです。

操作USD / ユニット
V4.1 または V4.1 Utility のラスター$0.035 / 35
V4.1 Pro または Utility Pro のラスター$0.21 / 210
V4 のラスター / V4 Pro のラスター$0.04 / 40；$0.25 / 250
V3 のラスター / V2 のラスター$0.04 / 40；$0.022 / 22
V4.1/V4 の標準ベクター$0.08 / 80
V4.1/V4 Pro のベクター$0.30 / 300
V3 のベクター / V2 のベクター$0.08 / 80；$0.044 / 44
V3 のラスター/ベクターの画像から画像への変換、インペイント、アウトペイント、背景操作画像 1 枚あたり $0.04 / 40；$0.08 / 80
スタイル作成リクエスト 1 件あたり $0.04 / 40
ベクター化 / 背景削除それぞれ $0.01 / 10
くっきり拡大 / クリエイティブ拡大 / 消去 / バリエーション生成$0.004 / 4；$0.25 / 250；$0.002 / 2；$0.04 / 40
プロンプトの拡張$0.01 / 10

更新時には、公開 API 料金ページと一般向けの料金情報に一時的な不一致が生じることがあります。実行前に API 料金ページと /users/me を確認してください。予想ユニット数は、操作ごとの料金に要求する出力数を掛けて算出し、再試行や不確実性に備えた予備分を加算して、予算に達したら停止してください。

現在の料金表では画像から画像への変換料金は V3/V3 Vector のみ記載されており、エンドポイントガイドにはより幅広い画像から画像への変換モデルパラメーターと Explore ルートが公開されているにもかかわらず、Explore/Explore Similar の料金は記載されていません。/users/me で確認できるのは残高であり、未掲載の操作料金ではありません。V4/V4.1 の画像から画像への変換や Explore のワークロードを予算に含める前に、Recraft サポートまたは営業担当者から書面で確認を得てください。

公式情報源

2026-07-09 確認済み：

明示的に利用不可または不明確な情報

確認時点では、公式の公開資料に以下の情報は記載されていませんでした。

  • モデルの正式な非推奨日またはライフサイクル保証。
  • マーケティング上の説明があるにもかかわらず、非同期/バッチジョブ、ポーリング、キャンセル、Webhook、署名、優先推論に関する公開スキーマ。
  • 完全かつ安定したエラーコード/本文の仕様。
  • 冪等性キーの保証。
  • 公開 API ガイドにおける生成レイテンシまたは稼働時間の SLA。
  • Studio のモックアップレイヤーの変形/合成を行う公開 API エンドポイント。
  • すべての API 出力に適用される包括的な来歴/C2PA 保証。
  • 法務、Appendix、信頼性に関する各ページ間で完全に一致する、単一のデフォルト保持期間に関する説明。
  • 現在のエンドポイントの説明とモデルパラメーター一覧の間で整合性の取れた、V4.1 の画像から画像への変換の互換性に関する説明。
  • V4/V4.1 の画像から画像への変換、または Explore/Explore Similar の公開済み操作料金。

これらの不足情報を、推測したフィールドやルートで補わないでください。本番運用上必要な場合は、Recraft サポートまたは営業担当者に書面で確認してください。

コメント

Markdown 対応