Skip to main content
Uploading images to the Wesog Search platform expands the tool’s search capabilities for a given organization by processing those images and adding them to the pool of images that can be retrieved via Wesog Search text queries. Ingestion can be performed either synchronously or asynchronously. However, since this process involves not only operations on our available hardware but also external requests to fetch the images, we recommend using the asynchronous mode, which will create an operation that can be queried afterwards.

​
Upload single image (POST /imgs/{item_id})

​
Parameters

This endpoint allows uploading a new image by explicitly indicating the unique identifier of the image in the URL. This identifier must be unique for each image and cannot be repeated with any other image already stored in the system. Additionally, like in the case of update and delete endpoints, the following parameters can be sent as Query Parameters:
ParameterTypeRequiredDescription
waitBooleanNoEnables ‘Synchronous’ mode. When true, waits until operation completes (default: false)
strictBooleanNoEnables ‘Strict’ mode. When true, fails if image ID already exists. When false, allows upsert (default: false)
urgentBooleanNoEnables ‘Faster’ mode. When true, operation is prioritized in queue (default: false)
langStringNoLanguage for tags (default: “en”, possible values: “en”, “es”, “fr”, “ru”)
Finally, it is necessary to specify the image metadata, among which the most important is the src, which is the URL of the image to be uploaded. The rest of the metadata is optional, but it is recommended to send it to enrich the information associated with the image and improve its subsequent search. The following table shows all the fields that can be sent in the request body:
FieldTypeRequiredDescription
srcStringYesURL of the image (used as source for the AI)
url_img_watermarkStringNoURL of the watermarked image
url_img_thumbnailStringNoURL of the thumbnail image
titleStringNoTitle of the image
headlineStringNoShort text describing the image
captionStringNoLong text describing the image
alt_textStringNoAlternative text for accessibility
ai_generatedBooleanNoIndicates if image was generated by AI
model_releaseBooleanNoWhether model release is available
property_releaseBooleanNoWhether property release is available
nsfwBooleanNoWhether content is not safe for work
statusStringNoCurrent status: Active, Withdrawn, Reserved, RDA Only
dateStringNoDate of image creation (YYYY-MM-DD format)
locationStringNoDetailed location description
cityStringNoCity name
countryStringNoCountry name
eventStringNoEvent name
authorStringNoCreator name
providerStringNoProvider identifier
shotStringNoType of photography shot
sceneStringNoScene description
techniqueStringNoTechnique used in creation
mediumStringNoMedium used in creation
keywordsArrayNoKeywords describing the image
categoriesArrayNoGeneral categories
collectionsArrayNoCollections the image belongs to

​
Request Example

A valid request example to this endpoint for uploading an image would be the following: 
curl --request POST \
  --url https://api.wesog.com/imgs/image123 \
  --header 'API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "src": "https://cdn.example.com/image.jpg",
  "url_img_watermark": "https://cdn.example.com/image/wm.jpg",
  "url_img_thumbnail": "https://cdn.example.com/image/thumb.jpg",
  "title": "image123",
  "headline": "Sunset over the Hudson River",
  "caption": "A vibrant orange sunset reflecting on the river with the city skyline in silhouette.",
  "alt_text": "Sunset cityscape view",
  "ai_generated": false,
  "model_release": true,
  "property_release": true,
  "nsfw": false,
  "status": "Active",
  "date": "2024-10-19",
  "location": "123 Main St, near Central Park",
  "city": "New York",
  "country": "United States",
  "event": "Oscar awards 2024",
  "author": "Jane Doe",
  "provider": "Acme Inc.",
  "shot": "Landscape",
  "scene": "Urban sunset",
  "technique": "Digital photography",
  "medium": "Photography",
  "keywords": [
    "sunset",
    "city",
    "skyline",
    "river"
  ],
  "categories": [
    "landscape",
    "urban",
    "nature"
  ],
  "collections": [
    "Street pics",
    "Exclusive"
  ]
}'

​
Responses

​
Image was uploaded successfully (Response Code: 201)

The different types of responses depend on whether the image upload process has been performed synchronously, if the task has been accepted but is pending asynchronous execution, or if some type of error has occurred during data validation: If the image has been uploaded successfully, all information related to the operation created to manage the image upload will be returned, for example: 
{
  "method": "add",
  "resource": "images",
  "num_total": 1,
  "num_good": 1,
  "num_bad": 0,
  "is_started": true,
  "all_good": true,
  "do_wait": false,
  "do_urgent": false,
  "do_strict": false,
  "idle_ms": 0,
  "exec_ms": 1500,
  "created_at": "2024-10-19T12:00:00Z",
  "started_at": "2024-10-19T12:00:01Z",
  "finished_at": "2024-10-19T12:00:02Z",
  "errors": []
}

​
Image upload accepted but pending (Response Code: 202)

If the request has simply been accepted but is pending asynchronous execution, an object with the ID of the operation created to manage the image upload will be returned, for example: 
{
  "operation_id": 123,
  "n_total": 123,
  "msg": "<string>"
}

​
Error in data validation (Response Code: 422)

And if, on the other hand, some error has occurred during the data validation stage, this will be shown with an error message indicating the reason for the failure, for example: 
{
  "detail": [
    {
      "loc": ["<field_name>"],
      "msg": "<error_message>",
      "type": "<error_type>"
    }
  ]
}

​
Upload multiple images (POST /imgs)

The multiple image upload method or endpoint allows sending a collection of JSON objects in a single message, with each object representing a different image with its own metadata. The entire upload process execution is treated as a general operation that may or may not be executed synchronously or asynchronously, depending on the parameters sent in the request.

​
Parameters

Like other endpoints that result in the internal generation of an operation, the following parameters can be received as Query Parameters:
ParameterTypeRequiredDescription
waitBooleanNoEnables ‘Synchronous’ mode. When true, waits until operation completes (default: false)
strictBooleanNoEnables ‘Strict’ mode. When true, fails if image ID already exists. When false, allows upsert (default: false)
urgentBooleanNoEnables ‘Faster’ mode. When true, operation is prioritized in queue (default: false)
langStringNoLanguage for tags (default: “en”, possible values: “en”, “es”, “pt”, “fr”, “ru”)
On the other hand, in the request body a list of JSON objects must be sent, each representing an image to upload. Each object must contain at least the id field, which is the unique identifier of the image, and the src field, which is the URL of the image to be uploaded. The rest of the fields are optional, but it is recommended to send them to enrich the information associated with each image. The following table shows the fields that can be sent in each object of the list:
FieldTypeRequiredDescription
idString/NumberYesUnique identifier of the image
srcStringYesURL of the image (used as source for the AI)
url_img_watermarkStringNoURL of the watermarked image
url_img_thumbnailStringNoURL of the thumbnail image
headlineStringNoShort text describing the image
captionStringNoLong text describing the image
dateStringNoDate of image creation (YYYY-MM-DD format)
ai_generatedBooleanNoIndicates if image was generated by AI (default: false)
statusStringNoCurrent status: Active, Withdrawn, Reserved, RDA Only (default: Active)
locationStringNoDetailed location description
cityStringNoCity name
countryStringNoCountry name
eventStringNoEvent name
authorStringNoCreator name
providerStringNoProvider identifier
shotStringNoType of photography shot
medium_lvl1StringNoPhotography or Illustration
medium_lvl2StringNoSpecific creation method
medium_lvl3StringNoMaterial used in creation
keywordsArray/StringNoKeywords describing the image (array or semicolon-separated string)
categoriesArray/StringNoGeneral categories (array or semicolon-separated string)
collectionsArrayNoCollections the image belongs to

​
Request Example

Here is an example of how to use the Wesog Search API for uploading multiple images: 
curl --request POST \
  --url https://api.wesog.com/imgs \
  --header 'API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "id": "image123",
    "src": "https://cdn.example.com/image/original.jpg",
    "url_img_watermark": "https://cdn.example.com/image/wm.jpg",
    "url_img_thumbnail": "https://cdn.example.com/image/thumb.jpg",
    "headline": "Sunset over the Hudson River",
    "caption": "A vibrant orange sunset reflecting on the river with the city skyline in silhouette.",
    "ai_generated": false,
    "status": "Active",
    "date": "2024-10-19",
    "location": "123 Main St, near Central Park",
    "city": "New York",
    "country": "United States",
    "event": "Oscar awards 2024",
    "author": "Jane Doe",
    "provider": "Acme Inc.",
    "shot": "Portrait",
    "medium_lvl1": "Photography",
    "medium_lvl2": "Drawing",
    "medium_lvl3": "Oil on canvas",
    "keywords": [
      "Tree",
      "Dog",
      "Ball",
      "Water"
    ],
    "categories": [
      "Sport",
      "Fashion",
      "Politics"
    ],
    "collections": [
      "Street pics",
      "Exclusive"
    ]
  }
]'

​
Responses

​
Images were uploaded successfully (Response Code: 201)

Similar to the scenario where only a single new image is requested to be sent to the Wesog service, in the case of sending multiple images, if they were processed and included within the system (or were processed and discarded due to some type of internal error), a response will be provided with a message including all relevant information related to the image upload process.
FieldTypeDescription
methodStringType of operation (e.g., “add”, “upd”, “del”)
resourceStringResource being operated on (e.g., “video”, “images”)
num_totalNumberTotal number of items in the operation
num_goodNumberNumber of items successfully processed
num_badNumberNumber of items that failed to process
is_startedBooleanWhether the operation has started execution
is_finishedBooleanWhether the operation has completed
all_goodBooleanWhether all items were successfully processed
do_waitBooleanWhether the operation was executed in synchronous mode
do_urgentBooleanWhether the operation was prioritized in the queue
do_strictBooleanWhether strict mode was enabled for the operation
idle_msNumberTime in milliseconds the operation waited before starting
exec_msNumberTime in milliseconds the operation took to execute
created_atStringTimestamp when the operation was created
started_atStringTimestamp when the operation started execution
finished_atStringTimestamp when the operation finished
errorsArrayList of error objects with id and msg fields for failed items

​
Images upload accepted but pending (Response Code: 202)

The process of uploading a set of images usually requires more time than uploading a single original image, depending on the amount of data sent to the service. For this reason, the type of response that will be shown predominantly in a short period of time after making the ingestion request will be this one. As seen previously when dealing with the process of uploading a single image, the operation ID, total number of images being processed, and a secondary message providing more information about the operation’s progress are sent, if necessary. 
{
  "operation_id": 123,
  "n_total": 123,
  "msg": "<string>"
}

​
Error in validation data (Response Code: 422)

This error occurs just like in the case of the individual image, when the format of the sent message does not match the expected format, described in the request section. This happens mainly when necessary fields such as src or id are not included. 
{
  "detail": [
    {
      "loc": ["<field_name>"],
      "msg": "<error_message>",
      "type": "<error_type>"
    }
  ]
}