Virtual Staging ART Developer API

Virtual Staging ART API を使うと、画像のアップロード、ステージングや片付けのリクエスト、ステータス確認、Webhook による完了通知を行えます。

Base URL

このページの例では、互換性維持のための /api/... パスを使っています。

https://www.virtualstaging.art/api/...

必要に応じて、同等の /v1/... パスも利用できます。

認証

すべての Developer API リクエストでは Bearer トークンを使用します。

Authorization: Bearer YOUR_API_TOKEN

API トークンは Virtual Staging ART のアカウント設定から発行できます。

ノーコード連携: Zapier

コードを書きたくない場合は、Zapier の公式 Virtual Staging ART インテグレーションを使って、7,000 以上のアプリにレンダーを連携できます。Zapier アプリは同じ API トークンと、下記の Webhook サブスクリプションエンドポイントを使用しています。

トリガー: Render Finished、Render Failed。アクション: Stage a Photo、Declutter a Photo、Upload Image。検索: Find Render Status。

基本的な流れ

多くの連携では、次の手順になります。

/api/image/upload で画像をアップロードするか、公開された image_url をそのまま使います。
/api/image/render/request または /api/image/render/declutter にリクエストします。
返ってきた upload_id で /api/image/check-status をポーリングするか、callback_url を指定して Webhook を待ちます。
完成した render_urls を自分のアプリで利用します。

1. 画像をアップロードする

Endpoint

POST /api/image/upload

Response

{
  "url": "https://..."
}

返ってきた url を、後続のレンダーリクエストの image_url として使います。

返却される url は、アップロード済み画像の有効期限のない公開URLです。短時間で失効する署名付きダウンロードURLではないため、後続のレンダーリクエストでも同じ image_url を継続利用できます。

Option A: Multipart upload

multipart/form-data で通常のファイルアップロードを行います。

フォームフィールド:

file

例:

curl -X POST "https://www.virtualstaging.art/api/image/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "[email protected]"

Option B: Base64 JSON upload

JSON で raw base64 または data URL を送れます。

raw base64 の例:

{
  "image_base64": "BASE64_HERE",
  "content_type": "image/jpeg"
}

data URL の例:

{
  "data_url": "data:image/png;base64,iVBORw0KGgoAAA..."
}

Upload limits

最大アップロードサイズ: 10 MB
対応形式:
- JPEG
- PNG
- WebP
- HEIC / HEIF

2. アップロードせずに自分の `image_url` を使う

すでに自社で画像をホストしている場合は、/api/image/upload を使わず、そのまま image_url をレンダーリクエストに渡せます。

image_url は次の条件を満たす必要があります。

画像ファイルそのものを指す URL であること
公開アクセス可能であること
https:// であること
通常の 200 レスポンスで画像ファイルを返すこと

失敗しやすい例:

有効期限付きの一時 URL
ログインや Cookie が必要な URL
画像ではなく HTML を返す共有ページ
localhost やプライベートネットワークの URL

3. ステージングをリクエストする

Endpoint

POST /api/image/render/request

Request body

{
  "image_url": "https://example.com/source.jpg",
  "room_type": "living",
  "style": "modern",
  "number_of_renders": 1,
  "upload_id": "optional-grouping-id",
  "layout_type": "studio",
  "ai_notes": "Keep the room bright and add a premium contemporary feel.",
  "callback_url": "https://example.com/callback",
  "tier": "premium"
}

Required fields

image_url
room_type
style

`tier` options

classic
- 未指定時のデフォルト
- 1つの upload group あたり最大 20 レンダー
premium
- この互換エンドポイントでは 1 クレジットあたり最大 8 レンダー

Supported `room_type`

living
bed
kitchen
office
dining
studio
ldk * premium only
bathroom * premium only
entrance * premium only

Legacy note: home_office も office のエイリアスとして受け付けます。

Supported `style`

modern
scandinavian
industrial
coastal
luxury
mid-century modern
farmhouse
standard
minimalist * premium only
japandi * premium only
bohemian * premium only
traditional * premium only

Optional fields

number_of_renders
- デフォルト: 1
- 1リクエストあたり最大: 10
upload_id
- 同じ画像に対する複数リクエストを同じ upload group にまとめます
- 同じ画像に追加でレンダリングしたい場合は、初回レスポンスで返された upload_id を再利用してください
- upload_id を省略した場合、この互換エンドポイントでは image_url の文字列完全一致で同一画像かどうかを判定します
layout_type
- 互換性のため studio をサポートします
callback_url
- 完了通知を送る Webhook URL
ai_notes * premium only
- モデル向けの追加テキスト指示
- 最大長: 500 文字
tier
- classic または premium
- 既存 API ユーザーは未指定時に classic になります

Response

{
  "upload_id": "uuid-or-existing-group-id",
  "status": "rendering",
  "tier": "classic"
}

4. 片付けをリクエストする

Endpoint

POST /api/image/render/declutter

`tier` options

classic
- 未指定時のデフォルト
- 1つの upload group あたり最大 20 レンダー
premium
- この互換エンドポイントでは 1 クレジットあたり最大 8 レンダー

Request body

{
  "image_url": "https://example.com/source.jpg",
  "number_of_renders": 1,
  "upload_id": "optional-grouping-id",
  "ai_notes": "Remove clutter while preserving the natural lighting.",
  "callback_url": "https://example.com/callback",
  "tier": "premium"
}

ai_notes は tier が premium の場合のみ利用できます。

Response

{
  "upload_id": "uuid-or-existing-group-id",
  "status": "rendering",
  "tier": "classic"
}

5. レンダーステータスを確認する

Endpoint

POST /api/image/check-status

推奨リクエスト

{
  "upload_id": "uuid-or-existing-group-id"
}

互換リクエスト

{
  "image_url": "https://example.com/source.jpg"
}

Response

{
  "status": "rendering"
}

取りうる値:

rendering
done
error

推奨される照会方法は upload_id です。

6. upload に対して何件レンダーしたか確認する

Endpoint

POST /api/image/check-rendering-amount

Request body

{
  "uploadId": "uuid-or-existing-group-id"
}

次の形式も使えます。

{
  "sourceImage": "https://example.com/source.jpg"
}

互換エイリアスも受け付けます。

{
  "upload_id": "uuid-or-existing-group-id",
  "image_url": "https://example.com/source.jpg"
}

Response

{
  "renderCount": 3,
  "limitExceeded": false,
  "maxRenders": 20
}

7. Webhook callbacks

レンダーリクエストに callback_url を指定すると、完了時に Virtual Staging ART から POST されます。

Success payload

{
  "status": "done",
  "render_urls": [
    "https://assets.example.com/render-1.jpg",
    "https://assets.example.com/render-2.jpg"
  ]
}

Error payload

{
  "status": "error",
  "error": "Internal server error. Please try again later."
}

8. Webhook サブスクリプション

リクエストごとの callback_url とは異なり、サブスクリプションは削除するまで、該当アカウントの全ての一致イベントを受け取り続けます。公式 Zapier 連携が使うモデルで、ほとんどの本番連携で推奨される方式です。

リクエストごとの callback とユーザー単位のサブスクリプションは独立しており、同じレンダー完了で両方が発火します。

サブスクリプションを作成

POST /v1/webhooks

リクエストボディ:

{
  "target_url": "https://example.com/my-hook",
  "event_type": "render.succeeded"
}

対応する event_type:

render.succeeded
render.failed

レスポンス:

{
  "id": "subscription-uuid",
  "target_url": "https://example.com/my-hook",
  "event_type": "render.succeeded",
  "created_at": "2026-05-15T12:00:00+00:00"
}

このエンドポイントは (target_url, event_type) に対して冪等で、同じ組み合わせを再度 POST すると重複作成ではなく既存のサブスクリプションを返します。

サブスクリプション一覧を取得

GET /v1/webhooks

有効なサブスクリプションの配列を返します。

サブスクリプションを削除

DELETE /v1/webhooks/{subscription_id}

204 No Content を返します。

サブスクリプションのペイロード

サブスクリプション配信のペイロードは、リクエストごとの callback よりも情報量が多くなっています。

{
  "event": "render.succeeded",
  "render_run_id": "uuid",
  "upload_id": "uuid",
  "tier": "premium",
  "flow": "staging",
  "render_urls": ["https://..."],
  "completed_at": "2026-05-15T12:00:30+00:00"
}

render.failed の場合:

{
  "event": "render.failed",
  "render_run_id": "uuid",
  "upload_id": "uuid",
  "tier": "classic",
  "flow": "staging",
  "error": "Provider rejected the request",
  "completed_at": "2026-05-15T12:00:30+00:00"
}

9. 最近のレンダー一覧

GET /v1/renders

クエリパラメーター:

limit — 取得件数の最大値（1〜100、デフォルト 25）
status — 任意のフィルタ: done、error、rendering

レスポンス:

[
  {
    "id": "uuid",
    "upload_id": "uuid",
    "status": "done",
    "tier": "premium",
    "flow": "staging",
    "room_type": "living_room",
    "style": "modern",
    "source_image_url": "https://...",
    "render_urls": ["https://..."],
    "error": null,
    "created_at": "2026-05-15T12:00:00+00:00",
    "completed_at": "2026-05-15T12:00:30+00:00"
  }
]

Developer API 経由で送信したレンダーを新しい順に返します。

10. 認証チェック

GET /v1/me

認証済みトークンの最小限のアイデンティティ情報を返します。レンダー送信前の接続確認に便利です。

{
  "user_id": "uuid",
  "email": "[email protected]",
  "name": "Developer Name"
}

既存 Virtual Staging 連携向けの互換性メモ

継続して使えるもの

従来の /api/... 画像系エンドポイントは引き続き利用可能
既存 API ユーザーは tier 未指定時に classic
繰り返しリクエスト時の upload_id グルーピングを維持
layout_type="studio" をサポート
callback payload は従来どおり status + render_urls

変更されたもの

旧 Vercel Blob upload handshake はサポートされなくなりました。

/api/image/upload は現在、次を受け付けます。

multipart/form-data
image_base64 を含む JSON
data_url を含む JSON

旧方式の Vercel アップロードを送ると、multipart または base64 upload へ切り替えるよう案内する明確なエラーを返します。

Common errors

400 リクエストボディ不正、画像形式不正、画像 URL 不正、未対応の content type、または render cap 超過
401 API トークン不正または未指定
402 クレジット不足
403 アカウント制限中
413 アップロードサイズ超過
503 一時的なサービス障害またはキュー処理失敗

Virtual Staging ART Developer API

Base URL

認証

ノーコード連携: Zapier

基本的な流れ

1. 画像をアップロードする

Endpoint

Response

Option A: Multipart upload

Option B: Base64 JSON upload

Upload limits

2. アップロードせずに自分の image_url を使う

3. ステージングをリクエストする

Endpoint

Request body

Required fields

tier options

Supported room_type

Supported style

Optional fields

Response

4. 片付けをリクエストする

Endpoint

tier options

Request body

Response

5. レンダーステータスを確認する

Endpoint

推奨リクエスト

互換リクエスト

Response

6. upload に対して何件レンダーしたか確認する

Endpoint

Request body

Response

7. Webhook callbacks

Success payload

Error payload

8. Webhook サブスクリプション

サブスクリプションを作成

サブスクリプション一覧を取得

サブスクリプションを削除

サブスクリプションのペイロード

9. 最近のレンダー一覧

10. 認証チェック

既存 Virtual Staging 連携向けの互換性メモ

継続して使えるもの

変更されたもの

Common errors

2. アップロードせずに自分の `image_url` を使う

`tier` options

Supported `room_type`

Supported `style`

`tier` options