Adds images to an Image Search instance.

Request URL

Protocol URL Method Parameter
HTTPS ${HOST}/v2/image/add POST JSON
For more information about ${HOST}, see Request syntax.

Request parameters

Parameter Type Required Description
InstanceName String Yes The name of the Image Search instance.
ProductId String Yes The unique ID of the commodity. The ID can be up to 512 characters in length.
Note A product ID can correspond to multiple image names.
PicName String Yes The name of the image. The name can be up to 512 characters in length.
Note
  • An image is uniquely identified by the values of the ProductId and PicName parameters.
  • If you add images that have the same ProductId and PicName for multiple times, the image that is added in the last operation overwrites the images that are added in previous operations.
PicContent String Yes The image file. The image file is encoded in Base64.
  • The file size of the image cannot exceed 4 MB.
  • Image Search supports the following image formats: PNG, JPG, JPEG, BMP, GIF, WEBP, TIFF, and PPM.
  • The transmission time-out period cannot exceed 5 seconds.
  • For product, and generic image searches, the length and the width of the image must range from 100 pixels to 4,096 pixels.
  • The image cannot contain rotation information.
CategoryId Integer No The category of the image. For more information, see Category reference.
Note
  • For product image searches, if you specify a category for an image, the specified category prevails. If you do not specify a category for an image, the system predicts the category, and returns the prediction result in the response.
  • For generic image searches, the system sets the category ID to 88888888, regardless of whether you specify a category for an image.
Crop Boolean No Specifies whether to recognize the subject in the image and search for images based on the recognized subject. Valid values: true and false. Default value: true.
  • true: The system recognizes the subject in the image, and searches for images based on the recognized subject. You can obtain the recognition result in the response.
  • false: The system does not recognize the subject of the image, and searches for images based on the entire image.
Region String No The subject area in the image. The subject area is in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left corner pixel. x2 and y2 represent the lower-right pixel.
CustomContent String No The user-defined content. The value can be up to 4,096 characters in length.
Note If you specify this parameter, the response includes this parameter and its value. You can add text, such as an image description.
IntAttr Integer No The integer attribute. The attribute can be used to filter images when you search for images. If you specify this parameter, the response includes this parameter and its value.
StrAttr String No The string attribute. The value can be up to 128 characters in length. The attribute can be used to filter images when you search for images. If you specify this parameter, the response includes this parameter and its value.

Response parameters

Parameter Type Example Description
Success Boolean true Indicates whether the request is successful.
RequestId String 36C43E96-8F68-44AA-B1AF-B1F7AB94A6C1 The ID of the request.
Code Integer 0 The error code. The value 0 indicates a request success. A value that is not 0 indicates a request failure.
Message String success The returned message.
PicInfo - - The results of category prediction and subject recognition.
└CategoryId Integer 88888888 The result of category prediction. If a category is specified in the request, the specified category prevails.
└Region String 280,486,232,351 The result of subject recognition. The subject area of the image is in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left corner pixel. x2 and y2 represent the lower-right pixel. If a subject area is specified in the request, the specified subject area prevails.

Examples

  • Sample requests
    URL: ${HOST}/v2/image/add
    POST Body:
     {
            "InstanceName": "demoinstance",
            "PicName": "test",
            "CustomContent": "demo content",
            "PicContent": "${Base64ImageContent}",
            "ProductId": "test",
            "IntAttr": "0",
            "StrAttr": "demo str attr"
        }
  • Sample responses
    {
        "PicInfo": {
            "Region": "111,697,XX,XX",
            "CategoryId": 0
        },
        "Message": "success",
        "RequestId": "B253A127-DF89-4DDC-A295-618DD22B00B2",
        "Success": true,
        "Code": 0
    }

Error codes

For more information, see Error codes.