Share via

Images - Create From Urls

  • Reference
Service:
Azure AI Services
API Version:
3.3

Add the provided images urls to the set of training images. This API accepts a batch of urls, and optionally tags, to create images. There is a limit of 64 images and 20 tags. If all images are successful created, 200(OK) status code will be returned. Otherwise, 207 (Multi-Status) status code will be returned and detail status for each image will be listed in the response payload.

POST {Endpoint}/customvision/v3.3/training/projects/{projectId}/images/urls

URI Parameters

Name In Required Type Description
Endpoint
 path True

string

Supported Cognitive Services endpoints.
projectId
 path True

string

uuid

The project id.

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
images

ImageUrlCreateEntry[]

metadata

object

The metadata of image. Limited to 50 key-value pairs per image. The length of key is limited to 256. The length of value is limited to 512.
tagIds

string[]

Responses

Name Type Description
200 OK

ImageCreateSummary

OK

Media Types: "application/json", "application/xml", "text/xml"
Other Status Codes

ImageCreateSummary

207

Media Types: "application/json", "application/xml", "text/xml"
Other Status Codes

CustomVisionError

Error response

Media Types: "application/json", "application/xml", "text/xml"

Security

Training-Key

Type: apiKey
In: header

Examples

Successful CreateImagesFromUrls request

Sample request

POST https://westus.api.cognitive.microsoft.com/customvision/v3.3/training/projects/64b822c5-8082-4b36-a426-27225f4aa18c/images/urls


{
  "images": [
    {
      "url": "{url to image}"
    }
  ],
  "tagIds": [
    "b607964f-7bd6-4a3b-a869-6791fb6aab87"
  ]
}

Sample response

Status code:
200 
{
  "isBatchSuccessful": true,
  "images": [
    {
      "sourceUrl": "{url to image}",
      "status": "OK",
      "image": {
        "id": "4d6eb844-42ee-42bc-bd6f-c32455ef07c9",
        "created": "2017-12-19T15:56:10Z",
        "width": 1095,
        "height": 900,
        "resizedImageUri": "{Resized Image Uri}",
        "originalImageUri": "{Image Uri}",
        "thumbnailUri": "{Thumbnail Uri}",
        "tags": [
          {
            "tagId": "b607964f-7bd6-4a3b-a869-6791fb6aab87",
            "created": "2017-12-19T15:56:09Z",
            "tagName": "tag name"
          }
        ]
      }
    }
  ]
}
Status code:
207 
{
  "isBatchSuccessful": false,
  "images": [
    {
      "sourceUrl": "{url to image}",
      "status": "OK",
      "image": {
        "id": "4d6eb844-42ee-42bc-bd6f-c32455ef07c9",
        "created": "2017-12-19T15:56:10Z",
        "width": 1095,
        "height": 900,
        "resizedImageUri": "{Resized Image Uri}",
        "originalImageUri": "{Image Uri}",
        "thumbnailUri": "{Thumbnail Uri}",
        "tags": [
          {
            "tagId": "b607964f-7bd6-4a3b-a869-6791fb6aab87",
            "created": "2017-12-19T15:56:09Z",
            "tagName": "tag name"
          }
        ]
      }
    },
    {
      "sourceUrl": "{url to image}",
      "status": "ErrorSource",
      "image": null
    }
  ]
}

Definitions

Name Description
CustomVisionError
CustomVisionErrorCodes

The error code.
Image

Image model to be sent as JSON.
ImageCreateResult
ImageCreateStatus

Status of the image creation.
ImageCreateSummary
ImageRegion
ImageTag
ImageUrlCreateBatch
ImageUrlCreateEntry
Region

CustomVisionError

Name Type Description
code

CustomVisionErrorCodes

The error code.
message

string

A message explaining the error reported by the service.

CustomVisionErrorCodes

The error code.

Name Type Description
BadRequest

string

BadRequestCannotMigrateProjectWithName

string

BadRequestClassificationTrainingValidationFailed

string

BadRequestCustomerManagedKeyRevoked

string

BadRequestDetectionTrainingNotAllowNegativeTag

string

BadRequestDetectionTrainingValidationFailed

string

BadRequestDomainNotSupportedForAdvancedTraining

string

BadRequestExceedIterationPerProjectLimit

string

BadRequestExceedProjectLimit

string

BadRequestExceedTagPerImageLimit

string

BadRequestExceedTagPerProjectLimit

string

BadRequestExceededBatchSize

string

BadRequestExceededQuota

string

BadRequestExportAlreadyInProgress

string

BadRequestExportPlatformNotSupportedForAdvancedTraining

string

BadRequestExportValidationFailed

string

BadRequestExportWhileTraining

string

BadRequestImageBatch

string

BadRequestImageDimensions

string

BadRequestImageExceededCount

string

BadRequestImageFormat

string

BadRequestImageMetadataKey

string

BadRequestImageMetadataValue

string

BadRequestImageRegions

string

BadRequestImageSizeBytes

string

BadRequestImageStream

string

BadRequestImageTags

string

BadRequestImageUrl

string

BadRequestInvalid

string

BadRequestInvalidArtifactUri

string

BadRequestInvalidEmailAddress

string

BadRequestInvalidIds

string

BadRequestInvalidImportToken

string

BadRequestInvalidPublishName

string

BadRequestInvalidPublishTarget

string

BadRequestIterationDescription

string

BadRequestIterationIsNotTrained

string

BadRequestIterationIsPublished

string

BadRequestIterationName

string

BadRequestIterationNameNotUnique

string

BadRequestIterationNotPublished

string

BadRequestIterationValidationFailed

string

BadRequestMultiClassClassificationTrainingValidationFailed

string

BadRequestMultiLabelClassificationTrainingValidationFailed

string

BadRequestMultipleGeneralProductTag

string

BadRequestMultipleNegativeTag

string

BadRequestNegativeAndRegularTagOnSameImage

string

BadRequestNotLimitedTrial

string

BadRequestNotSupported

string

BadRequestOperationNotSupported

string

BadRequestPredictionIdsExceededCount

string

BadRequestPredictionIdsMissing

string

BadRequestPredictionInvalidApplicationName

string

BadRequestPredictionInvalidQueryParameters

string

BadRequestPredictionResultsExceededCount

string

BadRequestPredictionTagsExceededCount

string

BadRequestProjectDescription

string

BadRequestProjectDuplicated

string

BadRequestProjectImagePreprocessingSettings

string

BadRequestProjectName

string

BadRequestProjectNameNotUnique

string

BadRequestProjectUnknownClassification

string

BadRequestProjectUnknownDomain

string

BadRequestProjectUnsupportedDomainTypeChange

string

BadRequestProjectUnsupportedExportPlatform

string

BadRequestRequiredParamIsNull

string

BadRequestReservedBudgetInHoursNotEnoughForAdvancedTraining

string

BadRequestSubscriptionApi

string

BadRequestTagDescription

string

BadRequestTagName

string

BadRequestTagNameNotUnique

string

BadRequestTagType

string

BadRequestTrainingAlreadyInProgress

string

BadRequestTrainingNotNeeded

string

BadRequestTrainingNotNeededButTrainingPipelineUpdated

string

BadRequestTrainingValidationFailed

string

BadRequestUnpublishFailed

string

BadRequestUnsupportedDomain

string

BadRequestWorkspaceCannotBeModified

string

BadRequestWorkspaceNotDeletable

string

Conflict

string

ConflictInvalid

string

ErrorExporterInvalidClassifier

string

ErrorExporterInvalidFeaturizer

string

ErrorExporterInvalidPlatform

string

ErrorFeaturizationAugmentationError

string

ErrorFeaturizationAugmentationUnavailable

string

ErrorFeaturizationInvalidFeaturizer

string

ErrorFeaturizationQueueTimeout

string

ErrorFeaturizationServiceUnavailable

string

ErrorFeaturizationUnrecognizedJob

string

ErrorInvalid

string

ErrorIterationCopyFailed

string

ErrorPrediction

string

ErrorPredictionModelNotCached

string

ErrorPredictionModelNotFound

string

ErrorPredictionServiceUnavailable

string

ErrorPredictionStorage

string

ErrorPreparePerformanceMigrationFailed

string

ErrorProjectExportRequestFailed

string

ErrorProjectImportRequestFailed

string

ErrorProjectInvalidDomain

string

ErrorProjectInvalidPipelineConfiguration

string

ErrorProjectInvalidWorkspace

string

ErrorProjectTrainingRequestFailed

string

ErrorRegionProposal

string

ErrorUnknown

string

ErrorUnknownBaseModel

string

Forbidden

string

ForbiddenDRModeEnabled

string

ForbiddenInvalid

string

ForbiddenUser

string

ForbiddenUserDisabled

string

ForbiddenUserDoesNotExist

string

ForbiddenUserInsufficientCapability

string

ForbiddenUserResource

string

ForbiddenUserSignupAllowanceExceeded

string

ForbiddenUserSignupDisabled

string

NoError

string

NotFound

string

NotFoundApimSubscription

string

NotFoundDomain

string

NotFoundImage

string

NotFoundInvalid

string

NotFoundIteration

string

NotFoundIterationPerformance

string

NotFoundProject

string

NotFoundProjectDefaultIteration

string

NotFoundTag

string

UnsupportedMediaType

string

Image

Image model to be sent as JSON.

Name Type Description
created

string

Date the image was created.
height

integer

Height of the image.
id

string

Id of the image.
metadata

object

Metadata associated with this image.
originalImageUri

string

The URI to the original uploaded 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.
regions

ImageRegion[]

Regions associated with this image.
resizedImageUri

string

The URI to the (resized) image used for training. 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.
tags

ImageTag[]

Tags associated with this image.
thumbnailUri

string

The URI to the thumbnail of the original 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

Width of the image.

ImageCreateResult

Name Type Description
image

Image

The image.
sourceUrl

string

Source URL of the image.
status

ImageCreateStatus

Status of the image creation.

ImageCreateStatus

Status of the image creation.

Name Type Description
ErrorImageFormat

string

ErrorImageSize

string

ErrorLimitExceed

string

ErrorNegativeAndRegularTagOnSameImage

string

ErrorRegionLimitExceed

string

ErrorSource

string

ErrorStorage

string

ErrorTagLimitExceed

string

ErrorUnknown

string

OK

string

OKDuplicate

string

ImageCreateSummary

Name Type Description
images

ImageCreateResult[]

List of the image creation results.
isBatchSuccessful

boolean

True if all of the images in the batch were created successfully, otherwise false.

ImageRegion

Name Type Description
created

string

height

number

Height.
left

number

Coordinate of the left boundary.
regionId

string

tagId

string

Id of the tag associated with this region.
tagName

string

top

number

Coordinate of the top boundary.
width

number

Width.

ImageTag

Name Type Description
created

string

tagId

string

tagName

string

ImageUrlCreateBatch

Name Type Description
images

ImageUrlCreateEntry[]

metadata

object

The metadata of image. Limited to 50 key-value pairs per image. The length of key is limited to 256. The length of value is limited to 512.
tagIds

string[]

ImageUrlCreateEntry

Name Type Description
regions

Region[]

tagIds

string[]

url

string

Url of the image.

Region

Name Type Description
height

number

Height.
left

number

Coordinate of the left boundary.
tagId

string

Id of the tag associated with this region.
top

number

Coordinate of the top boundary.
width

number

Width.