# Vision AI

Vision AI analyzes images you send us. Post a batch of image URLs, receive a permanent image id for each one, then collect the finished analysis as it lands: a scene category, detected features, text and people, safety signals, source provenance, and neutral alt text in every locale your project is configured for. Your hotels do not have to be in our catalogue first, so you can run it over imagery you already hold.

The alt text matters beyond merchandising. Describing every image is what accessibility legislation such as the European Accessibility Act asks of a traveler-facing site, and writing those descriptions by hand across a large gallery is the part that never gets done.

## Availability

Vision AI is enabled per project. If all three endpoints answer `404 NOT_FOUND` with `{"Error": {"Code": "NOT_FOUND", "Message": "Not found"}}`, your project is not enabled for it yet. That answer is about provisioning, not about your request, so contact us rather than debugging the payload.

---

## The Three Calls

`ingestImages` submits URLs, `getImages` polls the ids you were handed, and `listImages` shows what this project has submitted when you no longer hold the ids.

### 1. Submit

Send up to 100 images in one call. All images in a call belong to one hotel, and naming a hotel is optional: use `HotelID`, `GlobalHotelID`, or `ExternalHotelID` with `productid` or `giata`. Send no selector and the images live under a workspace reserved for your project. `HotelName` goes with a selector and is refused without one. Only `ExternalHotelID` with `giata` on its own can create a hotel we do not hold yet; every other selector must match a hotel in your project, a draft hotel that holds images you submitted and have not deleted (for example the one created from your earlier `giata`-alone submission), or your own workspace. The condition on your images applies to drafts only. Any other hotel answers `404` "Hotel not found", exactly like an id we do not know. `RoomRef` is an optional label of your own, echoed back on every read.

```bash
curl -X POST https://api.ygo.ai/v2/project/content/vision/ingestImages \
  -H "Authorization: Bearer your_api_token_here" \
  -H "X-Project-ID: 0192fb17-5dc6-7abc-8def-123456789abc" \
  -H "Content-Type: application/json" \
  -d '{
    "ExternalHotelID": { "productid": "ES-MALLR-K7MP2" },
    "HotelName": "Hotel Sol Bay",
    "Images": [
      { "URL": "https://cdn.example.com/rooms/dbl-sea-01.jpg", "RoomRef": "DBL-SEA" }
    ]
  }'
```

```json
{
  "Data": {
    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abe",
    "Images": [
      { "ImageID": "0192fb17-5dc6-7abc-8def-123456789abd", "URL": "https://cdn.example.com/rooms/dbl-sea-01.jpg", "Status": "pending" }
    ]
  }
}
```

Keep the `ImageID` values. They are permanent, and re-submitting a URL for the same hotel returns the same id.

### 2. Poll

`getImages` takes up to 100 ids, the same cap as one submission, and answers in request order so you can zip the result against your own list. Each entry carries `pending`, `completed`, `failed`, or `not_found`, and the analyzed `Image` object appears only on `completed`. Drop terminal ids from your next poll.

```bash
curl -X POST https://api.ygo.ai/v2/project/content/vision/getImages \
  -H "Authorization: Bearer your_api_token_here" \
  -H "X-Project-ID: 0192fb17-5dc6-7abc-8def-123456789abc" \
  -H "Content-Type: application/json" \
  -d '{ "ImageIDs": ["0192fb17-5dc6-7abc-8def-123456789abd"] }'
```

### 3. List

`listImages` returns your project's submissions newest first, filtered by `Status` and paginated with `Limit` and `Offset`; a `Status` filter covers your newest 10,000 submissions. Use it for a console view, or whenever the ids were lost between our response and your database write.

> **Info**
>
> **Asynchronous by design**
>
> There is no synchronous mode and no callback. Submission returns ids immediately and the analysis runs behind it, so poll with `getImages` or read `listImages` until the statuses settle.

---

## Limits and Billing

One call carries at most 100 images. Per project, you may submit 25,000 images and create 1,000 new hotels in a rolling 24 hour window. Breaching either returns `429 RATE_LIMIT_EXCEEDED` with a `Retry-After` header, having stored and billed nothing. A one off bulk load beyond those limits is a conversation with us.

You pay once per newly submitted image, at submission. Re-submitting a URL we already hold for you is free, so retries after a timeout or a lost response cost nothing, and polling and listing are free.

---

## What a Completed Image Carries

The `Image` object is the same one the enrichment API serves in a hotel gallery: `Category`, the label arrays, appeal and quality scores, dimensions and format, `DominantColor` and `BlurHash`, the detection domains (`Presence`, `Safety`, `TextDetections`, `FeatureDetections`), a `Nudity` assessment when a person is in the picture, `Source` provenance, and `Descriptions` keyed by locale. `FileMetadata` reports what the image file states about itself, `CaptureDate` and `Copyright`, when it states anything.

Where a detection carries a `Confidence`, that number is a measured score. A `Confidence` of `null` means the label was noted without one, so treat it as unscored rather than as zero. Optional fields are genuinely absent when they do not apply, so branch on whether a key is present.

> **Info**
>
> **Descriptions are accessibility alt text**
>
> Each entry in `Descriptions` is a neutral description of what the image shows, written to be used as alt text, not as marketing copy. The descriptions are plain strings; the image's own `Compliance` envelope marks them, with the rest of the analysis, as AI generated. See the AI-generated content marking section of the [Content Enrichment API](https://docs.ygo.ai/guides/content-enrichment.md) overview for how to read that envelope.

> **Tip**
>
> **Start with one batch**
>
> Submit a small batch without a hotel selector and poll it to completion, so you can confirm the locales and fields you need before wiring the flow into your catalogue.

See the OpenAPI specs for request and response details.

Need help? Reach our integration team at `integrations@ygo.ai`.
