Update existing images

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:

Parameter	Type	Required	Description
`wait`	Boolean	No	Enables ‘Synchronous’ mode. When true, waits until operation completes (default: false)
`urgent`	Boolean	No	Enqueue the operation associated at head of operation’s queue
`strict`	Boolean	No	Enables ‘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.

Field	Type	Required	Description
`src`	String	Yes	URL of the image (used as source for the AI)
`url_img_watermark`	String	No	URL of the watermarked image
`url_img_thumbnail`	String	No	URL of the thumbnail image
`title`	String	No	Title of the image
`headline`	String	No	Short text describing the image
`caption`	String	No	Long text describing the image
`alt_text`	String	No	Alternative text for accessibility
`ai_generated`	Boolean	No	Indicates if image was generated by AI
`model_release`	Boolean	No	Whether model release is available
`property_release`	Boolean	No	Whether property release is available
`nsfw`	Boolean	No	Whether content is not safe for work
`status`	String	No	Current status: Active, Withdrawn, Reserved, RDA Only
`date`	String	No	Date of image creation (YYYY-MM-DD format)
`location`	String	No	Detailed location description
`city`	String	No	City name
`country`	String	No	Country name
`event`	String	No	Event name
`author`	String	No	Creator name
`provider`	String	No	Provider identifier
`shot`	String	No	Type of photography shot
`scene`	String	No	Scene description
`technique`	String	No	Technique used in creation
`medium`	String	No	Medium used in creation
`keywords`	Array	No	Keywords describing the image
`categories`	Array	No	General categories
`collections`	Array	No	Collections 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.

Parameter	Type	Required	Description
`wait`	Boolean	No	Enables ‘Synchronous’ mode. When true, waits until operation completes (default: false)
`strict`	Boolean	No	Enables ‘Strict’ mode. When true, fails if image ID doesn’t exist. When false, ignores missing IDs (default: false)
`urgent`	Boolean	No	Enables ‘Faster’ mode. When true, operation is prioritized in queue (default: false)
`lang`	String	No	Language 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:

Field	Type	Required	Description
`id`	String/Number	Yes	Unique identifier of the image to update
Other fields	Various	No	Any 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>"
    }
  ]
}

Get Started

Manage your content

Monitoring your operations

Search

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

Parameters

Request Example

Responses

Image was updated successfully (Response Code: 200)

Image update accepted but pending (Response Code: 202)

Error in data validation (Response Code: 422)

Replace multiple images (`PUT /imgs`)

Parameters

Request Example

Responses

Images were updated successfully (Response Code: 200)

Images update accepted but pending (Response Code: 202)

Error in validation data (Response Code: 422)

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

​Parameters

​Request Example

​Responses

​Image was updated successfully (Response Code: 200)

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

​Error in data validation (Response Code: 422)

​Replace multiple images (PUT /imgs)

​Parameters

​Request Example

​Responses

​Images were updated successfully (Response Code: 200)

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

​Error in validation data (Response Code: 422)

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

Parameters

Request Example

Responses

Image was updated successfully (Response Code: 200)

Image update accepted but pending (Response Code: 202)

Error in data validation (Response Code: 422)

Replace multiple images (`PUT /imgs`)

Parameters

Request Example

Responses

Images were updated successfully (Response Code: 200)

Images update accepted but pending (Response Code: 202)

Error in validation data (Response Code: 422)