Upload new images

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.

Wesog Search does not extract metadata embedded in the image file itself (e.g. EXIF/IPTC data such as date taken, author, location, etc.). Any such information must be sent explicitly as part of the request body (title, date, author, location, keywords, etc.) so that it can be indexed and used for search and filtering.

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:

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 already exists. When false, allows upsert (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”, “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:

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

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:

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 already exists. When false, allows upsert (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”, “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:

Field	Type	Required	Description
`id`	String/Number	Yes	Unique identifier of the image
`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
`headline`	String	No	Short text describing the image
`caption`	String	No	Long text describing the image
`date`	String	No	Date of image creation (YYYY-MM-DD format)
`ai_generated`	Boolean	No	Indicates if image was generated by AI (default: false)
`status`	String	No	Current status: Active, Withdrawn, Reserved, RDA Only (default: Active)
`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
`medium_lvl1`	String	No	Photography or Illustration
`medium_lvl2`	String	No	Specific creation method
`medium_lvl3`	String	No	Material used in creation
`keywords`	Array/String	No	Keywords describing the image (array or semicolon-separated string)
`categories`	Array/String	No	General categories (array or semicolon-separated string)
`collections`	Array	No	Collections 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.

Field	Type	Description
`method`	String	Type of operation (e.g., “add”, “upd”, “del”)
`resource`	String	Resource being operated on (e.g., “video”, “images”)
`num_total`	Number	Total number of items in the operation
`num_good`	Number	Number of items successfully processed
`num_bad`	Number	Number of items that failed to process
`is_started`	Boolean	Whether the operation has started execution
`is_finished`	Boolean	Whether the operation has completed
`all_good`	Boolean	Whether all items were successfully processed
`do_wait`	Boolean	Whether the operation was executed in synchronous mode
`do_urgent`	Boolean	Whether the operation was prioritized in the queue
`do_strict`	Boolean	Whether strict mode was enabled for the operation
`idle_ms`	Number	Time in milliseconds the operation waited before starting
`exec_ms`	Number	Time in milliseconds the operation took to execute
`created_at`	String	Timestamp when the operation was created
`started_at`	String	Timestamp when the operation started execution
`finished_at`	String	Timestamp when the operation finished
`errors`	Array	List 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>"
    }
  ]
}

Get Started

Manage your content

Monitoring your operations

Search

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

Parameters

Request Example

Responses

Image was uploaded successfully (Response Code: 201)

Image upload accepted but pending (Response Code: 202)

Error in data validation (Response Code: 422)

Upload multiple images (`POST /imgs`)

Parameters

Request Example

Responses

Images were uploaded successfully (Response Code: 201)

Images upload accepted but pending (Response Code: 202)

Error in validation data (Response Code: 422)

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

​Parameters

​Request Example

​Responses

​Image was uploaded successfully (Response Code: 201)

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

​Error in data validation (Response Code: 422)

​Upload multiple images (POST /imgs)

​Parameters

​Request Example

​Responses

​Images were uploaded successfully (Response Code: 201)

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

​Error in validation data (Response Code: 422)

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

Parameters

Request Example

Responses

Image was uploaded successfully (Response Code: 201)

Image upload accepted but pending (Response Code: 202)

Error in data validation (Response Code: 422)

Upload multiple images (`POST /imgs`)

Parameters

Request Example

Responses

Images were uploaded successfully (Response Code: 201)

Images upload accepted but pending (Response Code: 202)

Error in validation data (Response Code: 422)