Vision

SDK method for analysing property photos — room category and alt text.

The client.vision namespace classifies a property photo into one of your room categories and, optionally, writes alt text for it. It runs under the AI profile for (your API key's caller service, featureKey) — default feature key room-vision. See Product AI & Vision for profiles, quotas and idempotency. Available in TypeScript, Python, and Go SDKs.

SDK	Install	Namespace
TypeScript	`npm install @caldera/platformxe-sdk` (1.8.0+)	`client.vision`
Python	`pip install platformxe` (1.7.0+)	`client.vision`
Go	`go get github.com/calderax/platformxe-go@v1.7.0`	`client.Vision`

Analyze a room photo

Send exactly one of imageUrl (public https) or imageBase64 (at most 8 MiB decoded). Pass an idempotency key to retry the same photo safely.

const room = await client.vision.analyzeRoom(
  {
    imageUrl: 'https://cdn.example.com/listing/kitchen.jpg',
    roomCategories: ['KITCHEN', 'BEDROOM', 'LIVING_ROOM', 'BATHROOM'],
    wantAltText: true,
    locale: 'en-NG',
  },
  { idempotencyKey: `photo-${photoId}` },
);

console.log(room.roomCategory);   // "KITCHEN" (or null when nothing fits)
console.log(room.roomConfidence); // 0.91
console.log(room.altText);
console.log(room.aiStatus);       // "OK" | "FALLBACK"

room = client.vision.analyze_room(
    room_categories=["KITCHEN", "BEDROOM", "LIVING_ROOM", "BATHROOM"],
    want_alt_text=True,
    image_url="https://cdn.example.com/listing/kitchen.jpg",
    locale="en-NG",
    idempotency_key=f"photo-{photo_id}",
)
print(room["roomCategory"], room["aiStatus"])

room, err := client.Vision.AnalyzeRoom(
    platformxe.AnalyzeRoomInput{
        ImageURL:       "https://cdn.example.com/listing/kitchen.jpg",
        RoomCategories: []string{"KITCHEN", "BEDROOM", "LIVING_ROOM", "BATHROOM"},
        WantAltText:    true,
        Locale:         "en-NG",
    },
    &platformxe.AnalyzeRoomOptions{IdempotencyKey: "photo-" + photoID},
)
if err == nil && room.RoomCategory != nil {
    fmt.Println(*room.RoomCategory, room.AiStatus)
}

A provider timeout or overload is not an error: the call returns 200 with aiStatus: "FALLBACK" and a deterministic answer ("Property photograph"). That answer is marked X-Idempotency-Cache: skip and is never stored under your idempotency key, so retrying the same key later reaches the provider again. Every other response is replayed for 24 hours under the same key (X-Idempotency-Cache: HIT).

Errors

Code	Status	Meaning
`BAD_REQUEST`	400	Neither or both image fields, an image over 8 MiB, a non-public URL, bad categories
`AI_PROFILE_NOT_FOUND` / `AI_PROFILE_DISABLED`	403	No active profile for your caller service + `featureKey`
`CONFLICT`	409	A request with the same idempotency key is still running
`AI_QUOTA_EXCEEDED`	429	The profile's daily request cap is reached (`Retry-After` to the next UTC midnight; never retried by the SDKs)
`VISION_NOT_CONFIGURED`	503	No vision provider (AI gateway or Azure fallback) is configured on that deployment
`IDEMPOTENCY_UNAVAILABLE`	503	The idempotency store is down for a keyed request — nothing ran, retry is safe
`SERVER_ERROR`	500	Unexpected failure

Scopes required

Method	Scope	Rate limit
`vision.analyzeRoom()`	`vision:analyze`	2,000/hr