Content Enrichment API / Vision AI
Ingest vision images
PageMore page actions
POST /v2/project/content/vision/ingestImages
Submit image URLs for analysis; each gets an image ID immediately.
Asynchronous: poll the IDs with getVisionImages until completed or failed.
- 1-100 images per request, each
URLabsolutehttps. - At most one selector (
HotelID,GlobalHotelIDorExternalHotelID), or none;HotelNamerequired with one, refused without. - Except
giataalone, a selector reaches only your project's hotels, your placeholder hotel (no selector, or its HotelID) and draft hotels holding images you submitted and have not deleted. Any other hotel answers like an unknown one: 404, as does a project without Vision AI. - Only
giataalone can create a hotel. - 429: daily cap reached (25,000 images or 1,000 new hotels per rolling 24 hours); wait
Retry-Afterseconds.
Example request
curl -X POST 'https://api.ygo.ai/v2/project/content/vision/ingestImages' \
-H "Authorization: Bearer $YGO_API_KEY" \
-H "X-Project-ID: $YGO_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"Images": [
{
"URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/"
},
{
"URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/"
}
]
}'Authorization
Authorization: Bearer <key>
Project-scoped API key
Headers
X-Project-IDstring (uuid) requiredProject UUID. Required for all project-scoped endpoints.
Request body required
application/json object IngestVisionImagesRequest
Request body for submitting image URLs. Provide at most one hotel selector, or none to submit images without a hotel.
HotelIDstring (uuid)Hotel UUID, one of three optional, mutually exclusive selectors. Resolves only: an unknown UUID or a hotel you cannot reach (see the operation description) returns 404.
GlobalHotelIDstringCross-tenant global hotel identifier, one of three optional and mutually exclusive selectors. Resolves only: an unknown identifier or a hotel you cannot reach (see the operation description) returns 404.
ExternalHotelIDmap of string to stringYour own hotel identifiers, sub-keys
productidandgiata, AND-combined. Unlessgiatais alone, a hotel you cannot reach (see the operation description) returns 404; onlygiataalone can create one.HotelNamestringName of the hotel, required with a selector and refused without one, max 500 characters. Used only when a hotel is created, never written onto one that already exists.
Imagesarray of object VisionImageSubmission requiredThe images to submit, between 1 and 100 per request. Every entry belongs to the hotel this request selects, or to the project's placeholder hotel when no selector is sent.
2 fields
URLstring (uri) requiredAbsolute https URL of the image. Maximum 4096 characters.
RoomRefstringOptional room code or name from your own system, stored with the submission and echoed back by getVisionImages. Maximum 200 characters.
Example request: Two images submitted without a hotel
{
"Images": [
{
"URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/"
},
{
"URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/"
}
]
}Example request: One image for a hotel identified by your own product code
{
"ExternalHotelID": {
"productid": "IBS-MAJ-4711"
},
"HotelName": "Hotel Bahia Azul",
"Images": [
{
"URL": "https://images.example-client.com/1234567/exterior-pool.jpg"
}
]
}Example request: Three images for a known hotel selected by its UUID, two carrying the client's room codes
{
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"HotelName": "Hotel Bahia Azul",
"Images": [
{
"URL": "https://images.example-client.com/1234567/lobby.jpg"
},
{
"URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
"RoomRef": "DBL-SEA"
},
{
"URL": "https://images.example-client.com/1234567/room-suite-1.jpg",
"RoomRef": "SUITE-1"
}
]
}Example request: Re-submitting two already known URLs alongside a new one
{
"ExternalHotelID": {
"productid": "IBS-MAJ-4711"
},
"HotelName": "Hotel Bahia Azul",
"Images": [
{
"URL": "https://images.example-client.com/1234567/lobby.jpg"
},
{
"URL": "https://images.example-client.com/1234567/restaurant.jpg"
},
{
"URL": "https://images.example-client.com/1234567/spa-old.jpg"
}
]
}Example request: Creating a hotel record: giata alone, not yet known
{
"ExternalHotelID": {
"giata": "1234567"
},
"HotelName": "Hotel Bahia Azul",
"Images": [
{
"URL": "https://images.example-client.com/1234567/exterior-pool.jpg"
}
]
}Responses
200 OK
Images accepted. Every submitted URL has an image ID; analysis runs asynchronously, so poll the returned IDs with getVisionImages.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object IngestVisionImagesResponse
Single-object response envelope wrapping the ingest result.
Dataobject IngestVisionImagesResult requiredThe hotel the images were attached to and the per-image outcome of the submission.
2 fields
HotelIDstring (uuid) requiredUUID of the hotel the submitted images belong to. For a submission that named no hotel this is the project's placeholder hotel, and every later hotel-less submission returns that same ID.
Imagesarray of object IngestedImage requiredOne entry per submitted image, in request order.
3 fields
ImageIDstring (uuid) requiredImage UUID to poll with getVisionImages. For a URL that was already submitted for this hotel, this is the ID of the image that already carries it.
URLstring (uri) requiredThe submitted image URL.
Statusstring requiredCurrent state of this image:
pendingkeep polling,completedthe result is ready to fetch,failedthe URL could not be fetched. Fix a failed URL and submit it again.
Example response: Both images are queued for analysis on the project's placeholder hotel
{
"Data": {
"HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
"Images": [
{
"ImageID": "0199b2d0-11a5-7c5e-8f21-6d0e4f88b521",
"URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/",
"Status": "pending"
},
{
"ImageID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
"URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
"Status": "pending"
}
]
}
}Example response: The product code resolved to a known hotel and the image is queued for analysis
{
"Data": {
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Images": [
{
"ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
"URL": "https://images.example-client.com/1234567/exterior-pool.jpg",
"Status": "pending"
}
]
}
}Example response: Three new images attached to the hotel that already existed
{
"Data": {
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Images": [
{
"ImageID": "0192fb21-2bb3-7def-9abc-2233445566bb",
"URL": "https://images.example-client.com/1234567/lobby.jpg",
"Status": "pending"
},
{
"ImageID": "0192fb22-3cc4-7def-9abc-3344556677cc",
"URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
"Status": "pending"
},
{
"ImageID": "0192fb23-4dd5-7def-9abc-4455667788dd",
"URL": "https://images.example-client.com/1234567/room-suite-1.jpg",
"Status": "pending"
}
]
}
}Example response: One known URL is already analyzed, the other was confirmed unreachable earlier, and the new URL is queued
{
"Data": {
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Images": [
{
"ImageID": "0192fb21-2bb3-7def-9abc-2233445566bb",
"URL": "https://images.example-client.com/1234567/lobby.jpg",
"Status": "completed"
},
{
"ImageID": "0192fb24-5ee6-7def-9abc-5566778899ee",
"URL": "https://images.example-client.com/1234567/restaurant.jpg",
"Status": "pending"
},
{
"ImageID": "0192fb25-6ff7-7def-9abc-66778899aabb",
"URL": "https://images.example-client.com/1234567/spa-old.jpg",
"Status": "failed"
}
]
}
}Example response: A hotel record was created for the GIATA ID and the image is queued for analysis
{
"Data": {
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"Images": [
{
"ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
"URL": "https://images.example-client.com/1234567/exterior-pool.jpg",
"Status": "pending"
}
]
}
}400 Bad Request
Bad Request: the request body failed validation. No hotel and no image is stored when a request is rejected.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
Example response: More than one hotel selector
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "HotelID",
"Message": "Provide exactly one of HotelID, GlobalHotelID, or ExternalHotelID (multiple were provided)"
}
]
}
}Example response: HotelID is not a valid UUID
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Invalid HotelID format"
}
}Example response: The giata sub-key is not a positive number
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "ExternalHotelID",
"Message": "ExternalHotelID.giata must be a positive number"
}
]
}
}Example response: HotelName missing on a submission that names a hotel
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "HotelName",
"Message": "HotelName is required"
}
]
}
}Example response: HotelName sent without a hotel selector
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "HotelName",
"Message": "HotelName requires a hotel selector (HotelID, GlobalHotelID or ExternalHotelID); omit it to submit images without a hotel"
}
]
}
}Example response: More than 100 images in one request
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "Images",
"Message": "Images cannot exceed 100 entries"
}
]
}
}Example response: An image URL is not an absolute https URL, or a RoomRef is too long
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "Images[3].URL",
"Message": "URL must be an absolute https URL"
},
{
"Field": "Images[5].RoomRef",
"Message": "RoomRef cannot exceed 200 characters"
}
]
}
}401 Unauthorized
Unauthorized: the API key is missing or invalid.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
Example response: Invalid API key
{
"Error": {
"Code": "UNAUTHORIZED",
"Message": "Invalid API key"
}
}403 Forbidden
Forbidden: the API key may not act on this project, or does not carry the content.generation:write permission this endpoint requires (INSUFFICIENT_SCOPE).
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
Example response: Missing required scope
{
"Error": {
"Code": "INSUFFICIENT_SCOPE",
"Message": "token lacks scope content.generation:write"
}
}Example response: Project access required
{
"Error": {
"Code": "FORBIDDEN",
"Message": "Project access required"
}
}404 Not Found
Not Found: Vision AI is not enabled for your project, the project does not exist, or the selector matched no hotel you can reach. Nothing is stored.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
Example response: Project or resource not found
{
"Error": {
"Code": "NOT_FOUND",
"Message": "Not found"
}
}Example response: The selector matched no hotel you can reach, and could not create one
{
"Error": {
"Code": "NOT_FOUND",
"Message": "Hotel not found"
}
}409 Conflict
Conflict: the GIATA ID is held by a hotel record that is not available for submission.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
Example response: The GIATA ID cannot be used for a submission
{
"Error": {
"Code": "ALREADY_EXISTS",
"Message": "GiataID is held by a hotel record that is not available for submission"
}
}429 Too Many Requests
Too Many Requests: a per-project daily cap was reached, 25,000 images or 1,000 new hotels per rolling 24 hours. Nothing is stored or metered, and Retry-After carries the seconds to wait.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Retry-AfterintegerNumber of seconds to wait before retrying the request. Present on 429 responses.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
Example response: Limit exceeded
{
"Error": {
"Code": "RATE_LIMIT_EXCEEDED",
"Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
}
}Example response: Daily image submission cap reached (25,000 per rolling 24 hours), Retry-After: 3600
{
"Error": {
"Code": "RATE_LIMIT_EXCEEDED",
"Message": "Daily image submission limit reached for this project. Retry after the number of seconds in the Retry-After header."
}
}Example response: Daily new-hotel cap reached (1,000 per rolling 24 hours), Retry-After: 3600
{
"Error": {
"Code": "RATE_LIMIT_EXCEEDED",
"Message": "Daily new-hotel limit reached for this project. Retry after the number of seconds in the Retry-After header."
}
}500 Internal Server Error
Internal Server Error: unexpected server error. Quote the X-Trace-ID response header when contacting support.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ErrorResponse
Standard v2 error response wrapper.
Errorobject ErrorDetail requiredError detail containing a machine-readable code and human-readable message.
3 fields
Codestring requiredMachine-readable error code for programmatic handling.
Messagestring requiredHuman-readable error message.
Fieldsarray of object FieldErrorField-level validation errors. Only present for VALIDATION_ERROR responses.
4 fields
Fieldstring requiredName of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.
Messagestring requiredHuman-readable validation error message for this field.
CodestringMachine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.
Paramsmap of string to anyMachine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.
Example response: Internal server error
{
"Error": {
"Code": "INTERNAL_ERROR",
"Message": "Failed to store images"
}
}