Skip to main content
Once image information is stored on the servers where the Wesog database is maintained, it is possible to update this data without needing to delete existing images, thanks to this endpoint. This allows modifying the metadata associated with images, such as their title, description, tags, etc., without needing to re-upload the complete image. Like with deletion and upload operations, updating can be performed on a single image or on a batch of images (recommended for updating large quantities of images). For this purpose, two different endpoints have been implemented, as explained below:

​
Replace a single image (PUT /imgs/{item_id})

This endpoint allows updating the metadata of a specific image using its unique identifier (item_id).

​
Parameters

In this case, the item_id, which is the unique identifier of the image to be updated, must be included in the URL of the endpoint. The other parameters that can be sent as query parameters are:
ParameterTypeRequiredDescription
waitBooleanNoEnables ‘Synchronous’ mode. When true, waits until operation completes (default: false)
urgentBooleanNoEnqueue the operation associated at head of operation’s queue
strictBooleanNoEnables ‘Strict’ mode. When true, fails if image ID doesn’t exist. When false, ignores missing IDs (default: false)
Additionally, in the body section a JSON object is expected that contains the new values for the image fields. This operation is a PUT, so the parameters that are not included in the body will be removed from the image metadata. This allows updating only the necessary metadata without needing to re-upload the complete image.
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
As can be verified, most fields are optional, since in case they are not directly indicated, an incremental update will be performed, maintaining the existing values that are not modified. This allows great flexibility when updating image metadata without needing to send all the information each time.

​
Request Example

curl --request PUT \
  --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",
  "headline": "Updated: Sunset over the Hudson River",
  "caption": "An updated vibrant orange sunset reflecting on the river with the city skyline in silhouette.",
  "keywords": [
    "sunset",
    "city",
    "skyline",
    "river",
    "updated"
  ],
  "categories": [
    "landscape",
    "urban"
  ]
}'

​
Responses

Updating an image internally triggers an operation whose status can be queried. Accordingly, the endpoint returns all information associated with that operation, enabling the client to identify the generated operation ID and check its status thereafter.

​
Image was updated successfully (Response Code: 200)

If the image has been updated successfully, all information related to the operation created to manage the image update will be returned, for example: 
{
  "method": "upd",
  "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": 1200,
  "created_at": "2024-10-19T12:00:00Z",
  "started_at": "2024-10-19T12:00:01Z",
  "finished_at": "2024-10-19T12:00:02Z",
  "errors": []
}

​
Image update 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 update will be returned, for example: 
{
  "operation_id": 123,
  "n_total": 1,
  "msg": "Image update accepted, processing in progress."
}

​
Error in data validation (Response Code: 422)

If 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>"
    }
  ]
}

​
Replace multiple images (PUT /imgs)

This endpoint allows you to replace data for multiple images at once. It’s useful for efficiently updating large quantities of images.

​
Parameters

This endpoint maintains the same Query Parameters as the previous endpoint, but also allows for a request body containing the data of the images to be updated.
ParameterTypeRequiredDescription
waitBooleanNoEnables ‘Synchronous’ mode. When true, waits until operation completes (default: false)
strictBooleanNoEnables ‘Strict’ mode. When true, fails if image ID doesn’t exist. When false, ignores missing IDs (default: false)
urgentBooleanNoEnables ‘Faster’ mode. When true, operation is prioritized in queue (default: false)
langStringNoLanguage for tags (default: “en”, possible values: “en”, “es”, “fr”, “de”, “pt”, “ru”)
Since this endpoint is specifically designed to allow for the update of multiple images at once, the request body must include a list of JSON objects, each containing an id field with the identifier of the image to be updated, along with the fields to be modified. For example: 
[
  {
    "id": "image123",
    "headline": "Updated sunset over the Hudson River",
    "caption": "An updated vibrant orange sunset reflecting on the river."
  },
  {
    "id": "image456", 
    "status": "Withdrawn",
    "keywords": ["landscape", "evening", "city"]
  },
  {
    "id": "image789",
    "author": "John Smith",
    "location": "Central Park, Manhattan"
  }
]
Thus, the structure of the JSON objects that should comprise the list is:
FieldTypeRequiredDescription
idString/NumberYesUnique identifier of the image to update
Other fieldsVariousNoAny field from the image schema that needs to be updated

​
Request Example

Here is an example of how to use the Wesog Search API for updating multiple images: 
curl --request PUT \
  --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.jpg",
    "url_img_watermark": "https://cdn.example.com/image/wm.jpg",
    "url_img_thumbnail": "https://cdn.example.com/image/thumb.jpg",
    "headline": "Updated: Sunset over the Hudson River",
    "caption": "An updated vibrant orange sunset reflecting on the river with the city skyline in silhouette.",
    "status": "Active",
    "date": "2024-10-19",
    "location": "123 Main St, near Central Park",
    "city": "New York",
    "country": "United States",
    "author": "Jane Doe",
    "keywords": [
      "sunset",
      "city",
      "skyline",
      "river",
      "updated"
    ],
    "categories": [
      "landscape",
      "urban"
    ],
    "collections": [
      "Street pics",
      "Exclusive"
    ]
  }
]'

​
Responses

​
Images were updated successfully (Response Code: 200)

Similar to the scenario where only a single image is requested to be updated to the Wesog service, in the case of updating multiple images, if they were processed and updated 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 update process.

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

The process of updating a set of images usually requires more time than updating a single 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 update request will be this one. As seen previously when dealing with the process of updating 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": 3,
  "msg": "Images update accepted, processing in progress."
}

​
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 id are not included. 
{
  "detail": [
    {
      "loc": ["<field_name>"],
      "msg": "<error_message>",
      "type": "<error_type>"
    }
  ]
}