Images - List Suggested
This API will fetch untagged images filtered by suggested tags Ids. It returns an empty array if no images are found.
POST {Endpoint}/customvision/v3.3/training/projects/{projectId}/images/suggested?iterationId={iterationId}URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
Endpoint
|
path | True |
string |
Supported Cognitive Services endpoints. |
|
project
|
path | True |
string (uuid) |
The project id. |
|
iteration
|
query | True |
string (uuid) |
IterationId to use for the suggested tags and regions. |
Request Header
Media Types: "application/json", "application/xml", "text/xml", "application/x-www-form-urlencoded"
| Name | Required | Type | Description |
|---|---|---|---|
| Training-Key | True |
string |
Request Body
Media Types: "application/json", "application/xml", "text/xml", "application/x-www-form-urlencoded"
| Name | Type | Description |
|---|---|---|
| continuation |
string |
Continuation Id for database pagination. Initially null but later used to paginate. |
| maxCount |
integer (int32) |
Maximum number of results you want to be returned in the response. |
| session |
string |
SessionId for database query. Initially set to null but later used to paginate. |
| sortBy |
OrderBy. Ordering mechanism for your results. |
|
| tagIds |
string[] (uuid) |
Existing TagIds in project to filter suggested tags on. |
| threshold |
number (double) |
Confidence threshold to filter suggested tags on. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
OK Media Types: "application/json", "application/xml", "text/xml" |
|
| Other Status Codes |
Error response Media Types: "application/json", "application/xml", "text/xml" |
Security
Training-Key
Type:
apiKey
In:
header
Examples
Successful QuerySuggestedImages request
Sample request
POST https://westus.api.cognitive.microsoft.com/customvision/v3.3/training/projects/bc3f7dad-5544-468c-8573-3ef04d55463e/images/suggested?iterationId=b7b9d99c-a2c6-4658-9900-a98d2ff5bc66
{
"tagIds": [
"b5f7e6a2-a481-49a6-afec-a7cef1af3544"
]
}
Sample response
{
"results": [
{
"id": "dfd2d346-3ed5-4e1e-857d-af4e32cec042",
"project": "8988643a-ae70-447d-9a22-15c4255e5ecb",
"iteration": "b7b9d99c-a2c6-4658-9900-a98d2ff5bc66",
"created": "2018-01-31T20:18:26Z",
"predictions": [
{
"tagId": "b5f7e6a2-a481-49a6-afec-a7cef1af3544",
"tagName": "Tag 1",
"probability": 1
},
{
"tagId": "45619cda-d1c9-4bc8-a3e1-87c5d81adbc3",
"tagName": "Tag 2",
"probability": 3.60627153E-12
}
],
"originalImageUri": "<image uri>",
"thumbnailUri": "<thumbnail uri>",
"resizedImageUri": "<resized image uri>",
"domain": "b30a91ae-e3c1-4f73-a81e-c270bff27c39"
}
],
"token": {
"session": "1:286613",
"continuation": "",
"maxCount": 0,
"sortBy": "Newest",
"tagIds": [
"b5f7e6a2-a481-49a6-afec-a7cef1af3544"
]
}
}Definitions
| Name | Description |
|---|---|
|
Bounding |
Bounding box that defines a region of an image. |
|
Custom |
|
|
Custom |
The error code. |
| Prediction |
Prediction result. |
|
Sort |
OrderBy. Ordering mechanism for your results. |
|
Stored |
Result of a suggested tags and regions request of the untagged image. |
|
Suggested |
The array of result images and token containing session and continuation Ids for the next query. |
|
Suggested |
Contains properties we need to fetch suggested tags for. For the first call, Session and continuation set to null. Then on subsequent calls, uses the session/continuation from the previous SuggestedTagAndRegionQuery result to fetch additional results. |
|
Tag |
Type of the predicted tag. |
BoundingBox
Bounding box that defines a region of an image.
| Name | Type | Description |
|---|---|---|
| height |
number (float) |
Height. |
| left |
number (float) |
Coordinate of the left boundary. |
| top |
number (float) |
Coordinate of the top boundary. |
| width |
number (float) |
Width. |
CustomVisionError
| Name | Type | Description |
|---|---|---|
| code |
The error code. |
|
| message |
string |
A message explaining the error reported by the service. |
CustomVisionErrorCodes
The error code.
| Value | Description |
|---|---|
| NoError | |
| BadRequest | |
| BadRequestExceededBatchSize | |
| BadRequestNotSupported | |
| BadRequestInvalidIds | |
| BadRequestProjectName | |
| BadRequestProjectNameNotUnique | |
| BadRequestProjectDescription | |
| BadRequestProjectUnknownDomain | |
| BadRequestProjectUnknownClassification | |
| BadRequestProjectUnsupportedDomainTypeChange | |
| BadRequestProjectUnsupportedExportPlatform | |
| BadRequestProjectImagePreprocessingSettings | |
| BadRequestProjectDuplicated | |
| BadRequestIterationName | |
| BadRequestIterationNameNotUnique | |
| BadRequestIterationDescription | |
| BadRequestIterationIsNotTrained | |
| BadRequestIterationValidationFailed | |
| BadRequestWorkspaceCannotBeModified | |
| BadRequestWorkspaceNotDeletable | |
| BadRequestTagName | |
| BadRequestTagNameNotUnique | |
| BadRequestTagDescription | |
| BadRequestTagType | |
| BadRequestMultipleNegativeTag | |
| BadRequestMultipleGeneralProductTag | |
| BadRequestImageTags | |
| BadRequestImageRegions | |
| BadRequestNegativeAndRegularTagOnSameImage | |
| BadRequestUnsupportedDomain | |
| BadRequestRequiredParamIsNull | |
| BadRequestIterationIsPublished | |
| BadRequestInvalidPublishName | |
| BadRequestInvalidPublishTarget | |
| BadRequestUnpublishFailed | |
| BadRequestIterationNotPublished | |
| BadRequestSubscriptionApi | |
| BadRequestExceedProjectLimit | |
| BadRequestExceedIterationPerProjectLimit | |
| BadRequestExceedTagPerProjectLimit | |
| BadRequestExceedTagPerImageLimit | |
| BadRequestExceededQuota | |
| BadRequestCannotMigrateProjectWithName | |
| BadRequestNotLimitedTrial | |
| BadRequestImageBatch | |
| BadRequestImageStream | |
| BadRequestImageUrl | |
| BadRequestImageFormat | |
| BadRequestImageSizeBytes | |
| BadRequestImageDimensions | |
| BadRequestImageExceededCount | |
| BadRequestTrainingNotNeeded | |
| BadRequestTrainingNotNeededButTrainingPipelineUpdated | |
| BadRequestTrainingValidationFailed | |
| BadRequestClassificationTrainingValidationFailed | |
| BadRequestMultiClassClassificationTrainingValidationFailed | |
| BadRequestMultiLabelClassificationTrainingValidationFailed | |
| BadRequestDetectionTrainingValidationFailed | |
| BadRequestTrainingAlreadyInProgress | |
| BadRequestDetectionTrainingNotAllowNegativeTag | |
| BadRequestInvalidEmailAddress | |
| BadRequestDomainNotSupportedForAdvancedTraining | |
| BadRequestExportPlatformNotSupportedForAdvancedTraining | |
| BadRequestReservedBudgetInHoursNotEnoughForAdvancedTraining | |
| BadRequestExportValidationFailed | |
| BadRequestExportAlreadyInProgress | |
| BadRequestPredictionIdsMissing | |
| BadRequestPredictionIdsExceededCount | |
| BadRequestPredictionTagsExceededCount | |
| BadRequestPredictionResultsExceededCount | |
| BadRequestPredictionInvalidApplicationName | |
| BadRequestPredictionInvalidQueryParameters | |
| BadRequestInvalidImportToken | |
| BadRequestExportWhileTraining | |
| BadRequestImageMetadataKey | |
| BadRequestImageMetadataValue | |
| BadRequestOperationNotSupported | |
| BadRequestInvalidArtifactUri | |
| BadRequestCustomerManagedKeyRevoked | |
| BadRequestInvalid | |
| UnsupportedMediaType | |
| Forbidden | |
| ForbiddenUser | |
| ForbiddenUserResource | |
| ForbiddenUserSignupDisabled | |
| ForbiddenUserSignupAllowanceExceeded | |
| ForbiddenUserDoesNotExist | |
| ForbiddenUserDisabled | |
| ForbiddenUserInsufficientCapability | |
| ForbiddenDRModeEnabled | |
| ForbiddenInvalid | |
| NotFound | |
| NotFoundProject | |
| NotFoundProjectDefaultIteration | |
| NotFoundIteration | |
| NotFoundIterationPerformance | |
| NotFoundTag | |
| NotFoundImage | |
| NotFoundDomain | |
| NotFoundApimSubscription | |
| NotFoundInvalid | |
| Conflict | |
| ConflictInvalid | |
| ErrorUnknown | |
| ErrorIterationCopyFailed | |
| ErrorPreparePerformanceMigrationFailed | |
| ErrorProjectInvalidWorkspace | |
| ErrorProjectInvalidPipelineConfiguration | |
| ErrorProjectInvalidDomain | |
| ErrorProjectTrainingRequestFailed | |
| ErrorProjectImportRequestFailed | |
| ErrorProjectExportRequestFailed | |
| ErrorFeaturizationServiceUnavailable | |
| ErrorFeaturizationQueueTimeout | |
| ErrorFeaturizationInvalidFeaturizer | |
| ErrorFeaturizationAugmentationUnavailable | |
| ErrorFeaturizationUnrecognizedJob | |
| ErrorFeaturizationAugmentationError | |
| ErrorExporterInvalidPlatform | |
| ErrorExporterInvalidFeaturizer | |
| ErrorExporterInvalidClassifier | |
| ErrorPredictionServiceUnavailable | |
| ErrorPredictionModelNotFound | |
| ErrorPredictionModelNotCached | |
| ErrorPrediction | |
| ErrorPredictionStorage | |
| ErrorRegionProposal | |
| ErrorUnknownBaseModel | |
| ErrorInvalid |
Prediction
Prediction result.
| Name | Type | Description |
|---|---|---|
| boundingBox |
Bounding box of the prediction. |
|
| probability |
number (float) |
Probability of the tag. |
| tagId |
string (uuid) |
Id of the predicted tag. |
| tagName |
string |
Name of the predicted tag. |
| tagType |
Type of the predicted tag. |
SortBy
OrderBy. Ordering mechanism for your results.
| Value | Description |
|---|---|
| UncertaintyAscending | |
| UncertaintyDescending |
StoredSuggestedTagAndRegion
Result of a suggested tags and regions request of the untagged image.
| Name | Type | Description |
|---|---|---|
| created |
string (date-time) |
Date this prediction was created. |
| domain |
string (uuid) |
Domain used for the prediction. |
| height |
integer (int32) |
Height of the resized image. |
| id |
string (uuid) |
Prediction Id. |
| iteration |
string (uuid) |
Iteration Id. |
| originalImageUri |
string |
The URI to the original prediction image. If VNET feature is enabled this will be a relative path to be used with GetArtifact, otherwise this will be an absolute URI to the resource. |
| predictionUncertainty |
number (double) |
Uncertainty (entropy) of suggested tags or regions per image. |
| predictions |
List of predictions. |
|
| project |
string (uuid) |
Project Id. |
| resizedImageUri |
string |
The URI to the (resized) prediction image. If VNET feature is enabled this will be a relative path to be used with GetArtifact, otherwise this will be an absolute URI to the resource. |
| thumbnailUri |
string |
The URI to the thumbnail of the original prediction image. If VNET feature is enabled this will be a relative path to be used with GetArtifact, otherwise this will be an absolute URI to the resource. |
| width |
integer (int32) |
Width of the resized image. |
SuggestedTagAndRegionQuery
The array of result images and token containing session and continuation Ids for the next query.
| Name | Type | Description |
|---|---|---|
| results |
Result of a suggested tags and regions request of the untagged image. |
|
| token |
Contains properties we need to fetch suggested tags for. |
SuggestedTagAndRegionQueryToken
Contains properties we need to fetch suggested tags for. For the first call, Session and continuation set to null. Then on subsequent calls, uses the session/continuation from the previous SuggestedTagAndRegionQuery result to fetch additional results.
| Name | Type | Description |
|---|---|---|
| continuation |
string |
Continuation Id for database pagination. Initially null but later used to paginate. |
| maxCount |
integer (int32) |
Maximum number of results you want to be returned in the response. |
| session |
string |
SessionId for database query. Initially set to null but later used to paginate. |
| sortBy |
OrderBy. Ordering mechanism for your results. |
|
| tagIds |
string[] (uuid) |
Existing TagIds in project to filter suggested tags on. |
| threshold |
number (double) |
Confidence threshold to filter suggested tags on. |
TagType
Type of the predicted tag.
| Value | Description |
|---|---|
| Regular | |
| Negative | |
| GeneralProduct |