Stagify.ai › API ドキュメント

Stagify API

API ダッシュボード

自分のコードから不動産写真をバーチャルステージングできます。HTTP リクエスト 1 回でステージング済み画像が 1 枚返ります。前払いクレジットは 1 枚 0.15 ドル。サブスクリプションも最低利用額もなく、請求が膨らむこともありません。

ベース URL: https://stagify.ai/api/v1
認証: Bearer stg_live_…
コンテンツタイプ: multipart/form-data

概要

この API が公開しているのは 1 つだけです。Web アプリの裏側にあるステージング処理そのものです。部屋の写真を送り、部屋タイプと家具スタイルを指定すると、同じレスポンスでステージング済み画像が返ります。ジョブキューはなく、正常系でポーリングするものもありません。

クレジットは画像 1 枚単位です。前払いで購入し、レンダリングが成功するたびに 1 つ消費します。失敗したレンダリングは自動的に返還されるので、受け取った写真の分だけを支払うことになります。残高が前払いである以上、キーを盗まれても損失は残高までです。月末の請求書はありません。

キーはサーバー間通信で使うものです。API は CORS ヘッダーを返さないため、ブラウザーから直接呼び出すことはできません。これは意図的な設計で、ブラウザーの JavaScript から届くキーは漏洩したキーです。キーは一度だけ表示し、保存するのはハッシュのみ、失効は即時です。

クイックスタート

API キーのページでキーを作成し、クレジットパックを購入して写真を送信してください。レスポンスにはステージング済み画像が data URL として含まれます。

curl https://stagify.ai/api/v1/renders \
  -H "Authorization: Bearer $STAGIFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@living-room.jpg" \
  -F "roomType=Living room" \
  -F "furnitureStyle=modern" \
  -F "labelVirtuallyStaged=true"

レンダリングには数分かかることがあります。クライアントの読み取りタイムアウトを 300 秒に設定し、同じ Idempotency-Key で再試行してください。1 枚の写真に対して二重に課金されないことを保証するのがこの仕組みです。

クレジットパック

料金を読み込み中…

リクエストパラメーター

POST /api/v1/renders を multipart/form-data で送信します。下記の許容値はすべて GET /api/v1/options からも JSON で提供されます。こちらは API キー不要なので、この表をハードコードせずクライアント側のプルダウンを生成できます。

フィールド	型	説明
`image`	file	必須。部屋の写真。JPEG、PNG、WebP、最大 25 MB。判定されるのは MIME タイプであり、拡張子ではありません。
`roomType`	enum	`Bedroom`、`Living room`、`Dining room`、`Kitchen`、`Office`、`Bathroom`、`Outdoors`、`Dorm`。既定値は `Living room`。大文字小文字とスペースを区別します。認識できない値は拒否されず、自由テキストとしてプロンプトに書き込まれます。つまり `Living Room` は `Living room` ではありません。
`furnitureStyle`	enum	`standard`、`modern`、`midcentury`、`scandinavian`、`luxury`、`coastal`、`farmhouse`、`custom`。既定値は `standard` で、認識できない値も黙ってこれになります。`custom` は組み込みのスタイル文の代わりに `additionalPrompt` を使います。
`additionalPrompt`	string	このレンダリング向けの自由記述の指示。
`removeFurniture`	boolean	ステージング前に部屋を空にします。`true` または `on` を送ってください。`1` や `yes` を含むそれ以外はすべて false と解釈されます。
`keepFurniture`	string	残すものを自由記述で指定します。例：`keep the dining table and the built-in shelves`。`removeFurniture` が有効なときだけ読まれます。500 文字。
`furnitureImage`	file[]	参考にする家具の写真を最大 5 枚。形式とサイズ上限は `image` と同じです。
`labelVirtuallyStaged`	boolean	出力画像に「Virtually staged」の表示を焼き付けます。
`stampStyle`	enum	`dark`、`light`、`minimal`、`banner`。既定値は `dark`。大文字小文字は区別せず、認識できない値は既定値に戻ります。
`stampScale`	number	`0.7`〜`1.6`、既定値は `1`。範囲外の値は拒否されず、境界値に丸められます。
`stampLang`	enum	表示の言語：`english`、`spanish`、`french`、`german`、`chinese`、`korean`、`portuguese`、`russian`、`italian`、`japanese`、`dutch`。既定値は `english`。
`variations`	integer	受け付けるのは `1` のみです。複数必要な場合は並行してリクエストしてください。

冪等性

レンダリングは数分間コネクションを保持します。つまり実際に痛いのは、処理が完了した後にソケットが切れる障害です。課金だけされて手元には何も残りません。すべてのリクエストに Idempotency-Key ヘッダーを付け、同じ値で再試行してください。

こちらの記録	再試行時の動作
成功済みのリクエスト、同一パラメーター	保存済みの結果を `X-Stagify-Replayed: true` 付きで返します。二重課金はありません。
まだ実行中のリクエスト	`409 REQUEST_IN_FLIGHT`。待ってから再試行してください。
レンダリング途中で放棄されたリクエスト	既存の課金のまま再実行します。最大 3 回まで。
同じキーで異なるパラメーター	`422 IDEMPOTENCY_KEY_REUSED`。新しいキーを使ってください。

ヘッダーの省略は許容されており、その場合は再送保護がありません。これが正直な既定動作です。写真からキーを導出することはしません。同じ部屋の本当に別々のレンダリングが衝突し、2 番目の呼び出し元が 1 番目の画像を受け取ってしまうからです。

バーチャルステージングの表示

MLS や NAR の多くの規則は、バーチャルステージングした写真にその旨を明示することを求めています。labelVirtuallyStaged はその表示をピクセルに焼き付けます。下流のツールで取り除けるメタデータとして付けるのではありません。

表示を付けられない場合、画像はラベルなしで納品されるのではなく差し止められ、呼び出しは 500 DISCLOSURE_STAMP_FAILED を返し、クレジットは返還されます。この挙動をオフにする方法はなく、キーごとの既定値でひそかに無効化することもできません。

エラー

すべての失敗は { "error": "…", "code": "…" } を返します。分岐は必ず code で行い、メッセージでは行わないでください。メッセージは変わりますが、コードは変わりません。

ステータス	コード	対処
401	`API_KEY_MISSING` / `API_KEY_INVALID` / `API_KEY_REVOKED`	`Authorization` ヘッダーを確認するか、新しいキーを発行してください。
402	`INSUFFICIENT_CREDITS`	チャージしてください。レスポンスボディに `credits_remaining` が含まれます。
403	`ACCOUNT_SUSPENDED`	サポートにご連絡ください。
400	`VARIATIONS_UNSUPPORTED`	この API は 1 リクエストにつき 1 枚を生成します。並行リクエストをご利用ください。
409	`REQUEST_IN_FLIGHT`	その冪等キーはまだ実行中です。待ってから再試行してください。
409	`CONCURRENCY_LIMIT`	同時レンダリングが多すぎます。数秒後に再試行してください。
422	`IDEMPOTENCY_KEY_REUSED`	同じキーを異なるパラメーターで再利用しました。新しいキーを使ってください。
422	`NO_IMAGE_GENERATED`	モデルが何も返しませんでした。返金済みです。再試行するか、別の写真をお試しください。
429	`RATE_LIMITED`	間隔を空けて再試行してください。
500	`DISCLOSURE_STAMP_FAILED`	表示を付けられなかったため画像は差し止められました。返金済みです。
500	`RENDER_FAILED`	返金済みです。サポートに連絡する際は `ref` をお知らせください。

その他のエンドポイント

GET /api/v1/options：上記すべての列挙型の許容値。API キーは不要です。
GET /api/v1/me：キーは有効か？アカウントと残高を返します。
GET /api/v1/credits：残高と累計。
GET /api/v1/renders/{id}：1 件のレンダリングの状態。

すべてのレスポンスに X-Stagify-Credits-Remaining が付くので、ポーリングせずに残高の減りを追えます。

ご質問、上限の引き上げ、カード以外での請求書払いは team@stagify.ai まで。