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 のアカウント設定から発行できます。

基本的な流れ

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

/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 として使います。

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 にまとめます
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."
}

既存 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

認証

基本的な流れ

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

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

継続して使えるもの

変更されたもの

Common errors

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

`tier` options

Supported `room_type`

Supported `style`

`tier` options