Content Enrichment API / Vision AI
List vision images
PageMore page actions
POST /v2/project/content/vision/listImages
List this project's submitted images, newest first, with the enriched image object for every image that is complete.
Analysis runs asynchronously, so an image listed as pending is still being worked on. An empty body {} returns the first page of everything this project has submitted.
Limitdefaults to 50, caps at 100;Offsetdefaults to 0.Statusfilters topending,completedorfailed; any other value returns 400.- Ordered by
SubmittedAtthenImageID, both descending. Datais the array itself;Pagination.Totalcounts the match.- A
Statusfilter covers your newest 10,000 submissions. - 404 means Vision AI is not enabled for your project.
- 429 means the rate limit was hit; wait
Retry-Afterseconds.
Example request
curl -X POST 'https://api.ygo.ai/v2/project/content/vision/listImages' \
-H "Authorization: Bearer $YGO_API_KEY" \
-H "X-Project-ID: $YGO_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{}'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 ListVisionImagesRequest
Filter and page this project's submitted images. Every field is optional, so an empty body {} returns the first page of every image the project has submitted.
StatusstringRestrict the list to one state; omit it to list every state. A filter covers your newest 10,000 submissions.
LimitintegerPage size. Defaults to 50 when omitted or 0; a value above 100 is reduced to 100 rather than refused.
OffsetintegerNumber of images to skip before this page, default 0. An offset past the last image returns an empty page.
Example request: First page of everything this project has submitted
{}Example request: Only the analyzed images, two per page
{
"Status": "completed",
"Limit": 2,
"Offset": 0
}Example request: An offset beyond the last entry
{
"Offset": 200
}Responses
200 OK
One page of this project's submitted images, newest first.
Headers
X-Trace-IDstringRequest trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.
Body
application/json object ListVisionImagesResponse
List response envelope: Data is the page of submitted images and Pagination describes the whole matching set.
Dataarray of object ListVisionImage requiredThe page of submitted images, newest first. Always an array: an empty page is [] and never null.
10 fields
ImageIDstring (uuid) requiredImage UUID, the same ID ingestVisionImages returned and getVisionImages polls.
URLstring (uri) requiredThe submitted image URL, normalized.
Statusstring requiredAnalysis state:
pendingstill being analyzed,completedImagecarries the result,failedthe URL could not be fetched.not_foundnever appears here.SubmittedAtstring (date-time) requiredRFC 3339 timestamp of the submission. It is the sort key, descending; re-submitting the same URL refreshes it, which moves the image back to the top of the list.
BatchIDstring (uuid) requiredIdentifier shared by every image submitted in the same ingestVisionImages request.
HotelIDstring (uuid) requiredUUID of the hotel this image is stored under.
HotelNamestringName of that hotel. Present for the placeholder hotel and for hotels that belong to your project, omitted otherwise.
IsPlaceholderHotelbooleanTrue when the image was submitted without a hotel and therefore sits on the project's placeholder hotel. Present only when it is true; omitted for an image submitted for a hotel.
RoomRefstringThe room code or name submitted with this image. Omitted when the image was submitted without one.
Imageobject ImageThe enriched image object. Present only when Status is
completed.26 fields
IDstring (uuid) requiredUnique image UUID.
URLstring (uri) requiredImage URL.
SourcestringDetected provenance of the pixels:
photo,render,illustrationorai_generated. Omitted when the image carries no provenance assessment.CategorystringVision-derived image category (e.g. exterior, room, pool, restaurant).
Featuresarray of stringVision-derived feature tags depicted in the image.
Moodarray of stringVision-derived mood descriptors.
Tagsarray of stringAdditional vision-derived tags.
Flagsarray of stringQuality / content flags raised by vision analysis. Omitted when empty.
AppealScoreintegerAppeal score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.
QualityScoreintegerTechnical quality score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.
AppealScoreVersionstringVersion stamp of the scorer that produced AppealScore, for example
app-v4; it may name an earlier version. Absent when AppealScore is -1 or a legacy score from before stamps existed.QualityScoreVersionstringVersion stamp of the scorer that produced QualityScore, for example
qs-v4; it may name an earlier version. Absent when QualityScore is -1, a legacy score, or a first-seen image's provisional score.WidthintegerImage width in pixels.
HeightintegerImage height in pixels.
FormatstringImage format (e.g. jpeg, png, webp).
FileSizeintegerFile size in bytes.
DominantColorstringDominant color as a hex string.
BlurHashstringBlurHash placeholder string for progressive loading.
FileMetadataobjectWhat the image file itself states in its embedded IPTC/EXIF/XMP metadata: capture date and copyright notice. Omitted when the file states neither; inside it, a value the file did not state has no key.
2 fields
CaptureDatestringDate the photograph was taken, at the precision the file stated:
2012-06-14,2012-06or2012. It carries no time of day and no timezone.CopyrightstringThe copyright notice the file carries, as the file wrote it. It names who to ask; it is not a machine-readable licence.
Descriptionsmap of string to stringNeutral alt text describing what the image shows, not marketing copy, keyed by BCP 47 language tag. More locales may be added after an image is first analyzed.
Complianceobject ComplianceEU AI Act Article 50(2) marker for this image. Always present with
AIGeneratedtrue: the category, features, mood, tags, scores and descriptions are model output,FileMetadatais not.1 field
AIGeneratedbooleanEU AI Act Art. 50(2) machine-readable marker:
truewhen the text content of the enclosing object is AI-generated. Always stated explicitly when the envelope is present.
Presencearray of object PresenceDetectionPeople and animals seen in the image, from the closed vocabulary person, adult, child, animal. Omitted when the image carries no presence measurement.
2 fields
Labelstring requiredWhat was seen:
person,adult,childoranimal.Confidencenumber (float) DetectionConfidence required nullableConfidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.
Safetymap of string to number (float)Safety confidences keyed by dimension,
InappropriateandOffTopic, each between 0 and 1 or null. Omitted when the image carries no safety measurement.TextDetectionsarray of object TextDetectionTexts read off the image, each with its kind. Omitted when the image carries no text measurement.
3 fields
Contentstring requiredThe text as it appears on the image. A password or access code printed after a password label is masked.
Labelstring requiredKind of text:
overlay,price,promotional,watermark,signageordocument.Confidencenumber (float) DetectionConfidence required nullableConfidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.
FeatureDetectionsarray of object FeatureDetectionThe image's features with the confidence measured for each, running parallel to
Features. Omitted when the image carries no feature measurement.2 fields
Labelstring requiredThe feature label, from the same vocabulary as Features.
Confidencenumber (float) DetectionConfidence required nullableConfidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.
NudityobjectNudity assessment: exposure score, reason and explicit flag, independent of
Safety.Inappropriate. Omitted when the assessment did not run or the image'sPresenceshows no person.3 fields
Scoreinteger requiredExposure score from 0 to 100. Anchors: 20 beach or casual wear, 40 standard swimwear, 60 revealing swimwear or lingerie, 80 partial nudity, 100 explicit.
Reasonstring requiredOne model-written sentence naming what drives the score, at most 240 characters. Not sanitized for markup, so escape it before rendering.
Explicitboolean requiredTrue from a score of 90 up. Whether a child is in the picture is answered by
Presence, not here.
Paginationobject Pagination requiredPagination metadata for a list response.
3 fields
Totalinteger requiredNumber of images matching the request across all pages, not the page size. With a
Statusfilter it covers your newest 10,000 submissions.Limitinteger requiredPage size actually applied, after the default and the cap.
Offsetinteger requiredNumber of images skipped before this page.
Example response: Four images: one still being analyzed, two analyzed, one unreachable — three submitted without a hotel and one for a hotel
{
"Data": [
{
"ImageID": "0199b2d0-11a5-7c5e-8f21-6d0e4f88b521",
"URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/",
"Status": "pending",
"SubmittedAt": "2026-09-09T16:04:51.812433Z",
"BatchID": "0199b2d0-11a4-7c5e-8f21-5c9d3e77a410",
"HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
"HotelName": "Vision AI API placeholder",
"IsPlaceholderHotel": true
},
{
"ImageID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
"URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
"Status": "completed",
"SubmittedAt": "2026-09-09T16:04:12.550118Z",
"BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
"HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
"HotelName": "Vision AI API placeholder",
"IsPlaceholderHotel": true,
"Image": {
"ID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
"URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
"Source": "photo",
"Category": "restaurant",
"Features": [
"indoor_seating",
"buffet"
],
"Mood": [
"warm",
"inviting"
],
"Tags": [
"breakfast"
],
"AppealScore": 74,
"QualityScore": 81,
"AppealScoreVersion": "app-v4",
"QualityScoreVersion": "qs-v4",
"Width": 2000,
"Height": 1333,
"Format": "jpeg",
"FileSize": 611000,
"DominantColor": "#8A6A48",
"BlurHash": "L6PZfSjE.AyE_3t7t7R**0o#DgR4",
"FileMetadata": {
"CaptureDate": "2012-06-14",
"Copyright": "© 2012 Hotel Sol S.A."
},
"Descriptions": {
"en-US": "Restaurant with buffet counters and set tables.",
"de-DE": "Restaurant mit Buffettheken und eingedeckten Tischen."
},
"Compliance": {
"AIGenerated": true
},
"FeatureDetections": [
{
"Label": "buffet",
"Confidence": 0.91
},
{
"Label": "indoor_seating",
"Confidence": 0.86
}
]
}
},
{
"ImageID": "0199b2c4-8e31-77aa-9c02-1a4c60b8c7f1",
"URL": "https://ucarecdn.com/7d4e9b21-6c3a-4f52-8e10-9b8a7c6d5e4f/",
"Status": "failed",
"SubmittedAt": "2026-09-09T16:04:12.550118Z",
"BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
"HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
"HotelName": "Vision AI API placeholder",
"IsPlaceholderHotel": true
},
{
"ImageID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
"URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
"Status": "completed",
"SubmittedAt": "2026-09-08T09:12:44.301882Z",
"BatchID": "0199a51f-4c22-7de8-b3a9-0f1e2d3c4b5a",
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"HotelName": "Hotel Bahia Azul",
"RoomRef": "DBL-SEA",
"Image": {
"ID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
"URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
"Source": "photo",
"Category": "room",
"Features": [
"sea_view",
"balcony",
"double_bed"
],
"Mood": [
"bright",
"calm"
],
"Tags": [
"sea_view"
],
"AppealScore": 82,
"QualityScore": 77,
"AppealScoreVersion": "app-v4",
"QualityScoreVersion": "qs-v4",
"Width": 1600,
"Height": 1067,
"Format": "jpeg",
"FileSize": 412000,
"DominantColor": "#2E6F95",
"BlurHash": "LEHV6nWB2yk8pyo0adR*",
"Descriptions": {
"en-US": "Double room with a balcony overlooking the sea.",
"de-DE": "Doppelzimmer mit Balkon und Meerblick."
},
"Compliance": {
"AIGenerated": true
},
"Presence": [
{
"Label": "adult",
"Confidence": 0.81
}
],
"Safety": {
"Inappropriate": 0.02,
"OffTopic": null
},
"FeatureDetections": [
{
"Label": "sea_view",
"Confidence": 0.94
},
{
"Label": "balcony",
"Confidence": 0.88
}
]
}
}
],
"Pagination": {
"Total": 4,
"Limit": 50,
"Offset": 0
}
}Example response: The two analyzed images, one page of two, and Total counts only what the filter matched
{
"Data": [
{
"ImageID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
"URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
"Status": "completed",
"SubmittedAt": "2026-09-09T16:04:12.550118Z",
"BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
"HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
"HotelName": "Vision AI API placeholder",
"IsPlaceholderHotel": true,
"Image": {
"ID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
"URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
"Source": "photo",
"Category": "restaurant",
"Features": [
"indoor_seating",
"buffet"
],
"Mood": [
"warm",
"inviting"
],
"Tags": [
"breakfast"
],
"AppealScore": 74,
"QualityScore": 81,
"AppealScoreVersion": "app-v4",
"QualityScoreVersion": "qs-v4",
"Width": 2000,
"Height": 1333,
"Format": "jpeg",
"FileSize": 611000,
"DominantColor": "#8A6A48",
"BlurHash": "L6PZfSjE.AyE_3t7t7R**0o#DgR4",
"Descriptions": {
"en-US": "Restaurant with buffet counters and set tables.",
"de-DE": "Restaurant mit Buffettheken und eingedeckten Tischen."
},
"Compliance": {
"AIGenerated": true
}
}
},
{
"ImageID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
"URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
"Status": "completed",
"SubmittedAt": "2026-09-08T09:12:44.301882Z",
"BatchID": "0199a51f-4c22-7de8-b3a9-0f1e2d3c4b5a",
"HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
"HotelName": "Hotel Bahia Azul",
"RoomRef": "DBL-SEA",
"Image": {
"ID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
"URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
"Source": "photo",
"Category": "room",
"Features": [
"sea_view",
"balcony",
"double_bed"
],
"Mood": [
"bright",
"calm"
],
"Tags": [
"sea_view"
],
"AppealScore": 82,
"QualityScore": 77,
"AppealScoreVersion": "app-v4",
"QualityScoreVersion": "qs-v4",
"Width": 1600,
"Height": 1067,
"Format": "jpeg",
"FileSize": 412000,
"DominantColor": "#2E6F95",
"BlurHash": "LEHV6nWB2yk8pyo0adR*",
"Descriptions": {
"en-US": "Double room with a balcony overlooking the sea.",
"de-DE": "Doppelzimmer mit Balkon und Meerblick."
},
"Compliance": {
"AIGenerated": true
}
}
}
],
"Pagination": {
"Total": 2,
"Limit": 2,
"Offset": 0
}
}Example response: An empty page: Images is [], and Total still counts every match
{
"Data": [],
"Pagination": {
"Total": 4,
"Limit": 50,
"Offset": 200
}
}400 Bad Request
Bad Request: the request body or the Status value is invalid. Limit and Offset are clamped to the accepted range, never 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.
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: Status is not one of the three states
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Validation failed",
"Fields": [
{
"Field": "Status",
"Message": "Status must be omitted or one of pending, completed, failed"
}
]
}
}Example response: The request body is not valid JSON, or a field has the wrong type
{
"Error": {
"Code": "VALIDATION_ERROR",
"Message": "Invalid request body"
}
}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.
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.catalog:read 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.
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.catalog:read"
}
}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, or the project does not exist. A project with no submissions is an empty page, not a 404.
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.
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"
}
}429 Too Many Requests
Too Many Requests: the rate limit was exceeded. Retry-After carries the number of seconds to wait before retrying.
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.
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."
}
}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.
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 load images"
}
}