Content Enrichment
Vision AI
PageMore page actions
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.
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" }
]
}'
{
"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.
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.
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.
See the OpenAPI specs for request and response details.
Need help? Reach our integration team at integrations@ygo.ai.
