使用ガイド
recraft/crisp-upscale 入門ガイド:画像アップスケール API の導入ポイントと課金
能力の境界から枚数課金まで、開発者が画像アップスケールを安定的に本番フローへ導入する方法
- モデル
- recraft-crisp-upscale
このページの内容
crisp-upscale が解決する課題
すでに存在するが解像度が足りない画像を、より大きなサイズでエッジのくっきりしたバージョンに変換する——これが recraft/crisp-upscale の役割です。これは image-to-image(画像から画像へ) のカテゴリに属します。1枚の画像を渡すと、アップスケールされた画像が返ってきます。入力側にテキストプロンプトの位置はなく、出力タイプは画像に固定されています。
この種のモデルが解決する問題は具体的です:
- 素材サイズが統一されていない。ユーザーがアップロードした画像、過去のコンテンツライブラリ内の画像、サードパーティの提携先から提供された画像など、解像度はまちまちなのに、フロントエンドの表示サイズはデザイン要件で固定されている。
- 古いコンテンツを再利用する必要がある。数年前の挿絵、スクリーンショット、サムネイルをそのまま大きなコンテナに置くとぼやけてしまう。
- 生成結果の仕上げ。あらゆる画像生成・編集パイプラインの末端で、最終サイズを届けるためのアップスケール工程が必要になることがある。
もしあなたのニーズが「一文から画像を生成する」ことであれば、それはこのモデルの範囲外です。もし「手元に1枚の画像があり、それをより大きく鮮明にしたい」のであれば、それこそがこのモデルの出番です。判断基準は簡単です:呼び出し前に具体的な画像ファイルをすでに持っているかどうか。持っていればこれを使い、持っていなければまず生成の問題を別の場所で解決してください。
開発者にとって、このような単一責務はむしろ好都合です。インターフェースのセマンティクスはシンプルで、入出力構造は安定しており、失敗原因も特定しやすくなります。アップスケールは独立してテストでき、独立してロールバックできる工程であり、プロンプトエンジニアリングと絡み合うことはありません。

能力の境界:できること、期待してはいけないこと
crisp-upscale を「専任の拡大担当」として使えば、期待がずれることはありません。
できること
- 既存の画像を受け取り、アップスケールされた画像を出力する。標準的な image-to-image 変換です。
- 拡大と同時に鮮明さの表現を改善する。これが「crisp」という名前に込められた方向性です。
- パイプライン内の独立した工程として繰り返し呼び出せる。入出力はどちらも画像で、余計なテキスト状態を持ち込みません。
- 同質な素材のバッチ処理に適している。たとえば、あるバッチの商品画像をまとめて目標サイズに引き上げるなど。
やらない・できないこと
- テキストプロンプトから画像を生成することはありません。 これは text-to-image モデルではなく、入力に prompt という役割はありません。
- 画面内容の理解は行いません。 描き直し、スタイル変更、背景の差し替え、欠落した主体の補完などはしてくれません。そうしたニーズは生成・編集系モデルの領域です。
- ゼロから細部を創造することはできません。 アップスケールは本質的に既存のピクセルに基づく推論であり、元画像がひどくぼやけていたり、圧縮アーティファクトが極端に多かったり、主体そのものの情報が不足していたりすると、アップスケール結果も制限を受けます。入力品質が出力の天井を決めます。
- 拡大倍率や目標解像度は指定できません。 現在の公開パラメータは必須の画像公開 URL
image_urlのみで、形式は JPEG、PNG、WEBP に対応し、単一ファイルは 10MB 以下です。テキストプロンプトも、倍率や出力サイズのパラメータもありません。
実践的な判断として:手元の最も質の悪い業務素材でまず一巡試験するのがおすすめで、精巧にレタッチしたサンプル画像を使うべきではありません。最も悪い入力でアップスケールした結果が許容できない場合、問題は多くの場合、呼び出し側ではなく入力側にあります。

呼び出し前に確認すべき入力・出力仕様
HiAPI.ai の統一インターフェースに接続する際、以下のチェックリストを済ませてから業務コードを書けば、大部分の手戻りを省けます。
入力側
- ファイルが正常にデコードできるか。 まずローカルで形式と整合性を検証し、破損ファイルは送らないこと。無駄になるのはあなたの呼び出し回数です。
- ファイルが入力制約を満たしているか。 公開されている制約は形式が JPEG、PNG、WEBP で、単一ファイルは 10MB 以下です。元画像が小さすぎると拡大のメリットは限られ、大きすぎる場合はまず容量超過を確認してください。
- 色と透明チャンネル。 公開形式は JPEG、PNG、WEBP です。透明チャンネルを持つものやこのリストにないソースは、まずサンプルで出力が想定通りか確認してください。
- ファイル容量。 大きなファイルのアップロード時間とタイムアウト設定を合わせてください。デフォルトの短いタイムアウトで大きな画像を処理しようとしないこと。
出力側
- 出力サイズ。 リクエストで目標解像度は指定できません。導入時に異なるサイズの元画像を数枚使って「元画像サイズ → 出力サイズ」の実際の挙動を確認し、独自の対照表を作ってください。公開されていない命名档位に基づいて出力を仮定しないこと。
- 出力形式と容量。 アップスケール後のファイルは通常より大きくなります。下流のストレージと帯域幅を事前に見積もってください。
- 鮮明さの主観的な受け入れ基準。 何を「十分に鮮明」とするかを事前に定義しないと、達成度を判断できません。
パラメータ側
現在の公開パラメータは必須の image_url のみです。倍率、目標解像度、プロンプト、その他の未公開パラメータを勝手に追加せず、まずこの1項目で最小リクエストを通してください。
最小の検証順序:小さな1枚で通す → 業務の典型的な画像に差し替える → 最も品質の悪い画像に差し替える → 最大サイズの画像に差し替える。4ステップすべて通ってから、バッチ化を検討してください。

枚数課金:単価の計算方法
crisp-upscale の課金基準は枚数課金です——1回の成功した呼び出しが1枚の画像に対応し、1回の課金に対応します。価格は1档のみ:$0.004/枚。
利用量の見積もり方
月額費用 ≈ 月間呼び出し枚数 × $0.004。実際に管理すべき変数は1つだけ:月間呼び出し枚数です。これは3つの因子の積で得られます:
- 1日あたりに処理する業務オブジェクト数;
- オブジェクトあたり平均でアップスケールが必要な画像数;
- リトライと手戻りによる追加係数。
3番目が最も見落とされやすい項目です。失敗リトライ、画質不満による再処理、同じ画像が異なるフローで重複処理されることなどにより、実際の枚数は業務予想を上回ります。この3項目をそれぞれ記録しておけば、費用を呼び出し量に基づいて計算し、管理できます。
呼び出し量を制御するいくつかの手段
- 重複排除。 同じ画像(内容ハッシュで判定)は1回だけアップスケールし、結果を DB に保存して再利用します。コンテンツライブラリ内で同じ素材が複数箇所から参照される場面では、この項目だけでかなりの割合を節約できることがよくあります。
- 判定してから拡大。 元画像サイズがすでに表示要件を満たしていればアップスケールは不要です。サイズ判定を1つ追加するだけで無効な呼び出しを抑止できます。
- バッチ処理と非同期。 非リアルタイムの場面ではキューを使い、アップスケールをユーザーリクエストの経路から外します。リトライをまとめられ、タイムアウトによる重複送信も避けられます。
- 階層化戦略。 カバー画像、ファーストビューなど高価値な位置にはアップスケールを使い、リストのサムネイルは元画像をそのまま使う。予算を目に見える場所に集中させます。
- 予算ガードレール。 日次または週次で呼び出し上限を設定し、アラートを出します。あるループバグが枠を食い尽くすのを防ぐためです——この種の事故は枚数課金のモデルではコストが直接的に響きます。
まず全量サンプルの統計を一巡行い、そのうえでどれを拡大するか、どれだけ拡大するかを決める方が、勘で倍率を決めるよりはるかに信頼できます。
典型的な使い方とパイプラインの組み合わせ
アップスケールが単独で存在することは稀で、通常はパイプラインの一環です。以下は組み込みに適したいくつかの場面です。
素材の後処理
ユーザーや運用担当がアップロードした画像を、登録前に一括でアップスケール処理し、コンテンツライブラリのサイズ基準を統一します。こうすればフロントエンドは画像ごとに個別対応する必要がなくなり、デザイン稿も固定サイズで作れます。
古い画像・低品質画像の修復チェーン
過去コンテンツのスクリーンショットや過度に圧縮された挿絵は、まず基本的なクレンジング(トリミング、形式統一など)を行い、次に crisp-upscale に渡してアップスケールし、最後に目標サイズでトリミングして納品します。順序に注意:先に修復、後に拡大。修復可能な問題はアップスケール前に解決しておきます。
生成後の仕上げ
あらゆる画像生成・編集パイプラインの末端にアップスケール工程を付け、中間サイズの結果を納品サイズに引き上げられます。このチェーンの利点は疎結合であること——生成モデルを変えても、アップスケール工程は変更不要です。
パイプライン構造
アップロード → 検証(形式、サイズ、ハッシュによる重複排除)→ アップスケール呼び出し → 品質抜き取り検査 → ストレージ → CDN 配信。品質抜き取り検査は人手による確認でもよく、主要な素材のみ自動指標モニタリングでもかまいません。いずれにせよ「基準未達なら差し戻す」出口を用意しておきます。
エンジニアリング上の2つの注意点:アップスケール工程は冪等にすること(同じ入力なら同じ出力で、結果をキャッシュ可能);失敗時は独立してリトライでき、チェーン全体を再実行しないこと。
よくある落とし穴と検証チェックリスト
以下は導入過程で繰り返し発生する問題で、多くはリリース前に一度で回避できます。
よくある落とし穴
- 生成モデルとして使う。 欠落内容の補完や画面の変更を期待すると、必ず失望します。能力の境界を先にすり合わせておくこと。
- レタッチ済み画像で受け入れ検査する。 サンプルはきれいでも、リリース後にオンラインの低品質素材に遭遇すると失敗します。受け入れサンプルは実際の業務分布から取る必要があります。
- タイムアウト設定が短すぎる。 大きな画像の処理にはより長い時間がかかり、デフォルトのタイムアウトでは「実は成功したのにクライアントが諦めた」ことによる重複課金が起きやすくなります。
- 重複排除がない。 同じ素材が繰り返しアップスケールされ、請求額の増加が業務の増加と比例しなくなります。
- 公開されていない出力档位を仮定する。 リクエストで出力サイズは指定できません。ある命名解像度でレイアウトを組むと、下流をすべて作り直すことになりかねません。
- リトライの上限がない。 失敗即リトライで上限を設けないと、1回の障害で丸一日の予算を焼き尽くす可能性があります。
リリース前の検証チェックリスト
- 実際の業務分布の小さなサンプル(最も品質の悪い画像を含む)で全チェーンを通す;
- 入力仕様と出力サイズの実際の挙動を記録して確認する;
- 各呼び出しと各課金の対応関係を照合し、隠れた重複呼び出しがないことを確認する;
- 重複排除キャッシュのヒット率を検証する;
- タイムアウト、リトライ、サーキットブレーカーの戦略を検証する;
- 日常的な予算アラートと呼び出し量ダッシュボードを構築する;
- 小流量のカナリアリリースを行い、アップスケール前後の主観的画質と下流指標を比較してから全量切り替えする。
アップスケールのメリットは漸進的で、リスクも漸進的です。小さなサンプルでの比較をしっかり行えば、その後の大規模導入はほぼ運用作業になります。
1枚の画像を通すことから始め、仕様、課金、重複排除の3つを定めれば、crisp-upscale は画像パイプラインの中で静かに、しかし常に働き続ける工程として安定して機能します。