Skip to content

Commit 530b52e

Browse files
rjagiewichrjagiewich
authored
Merge pull request #49547 from Blackmist/freshness
rest api tutorial
2 parents c3a282d + c8d9780 commit 530b52e

File tree

3 files changed

+383
-0
lines changed

3 files changed

+383
-0
lines changed

‎articles/cognitive-services/Custom-Vision-Service/media/rest-api-tutorial/training-prediction-keys.png

137 KB
Loading

‎articles/cognitive-services/Custom-Vision-Service/rest-api-tutorial.md

Lines changed: 381 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,381 @@
1+
---
2+
title: Use the a Custom Vision Service REST API - Azure Cognitive Services | Microsoft Docs
3+
description: Use the REST API to create, train, test, and export a custom vision model.
4+
services: cognitive-services
5+
author: blackmist
6+
manager: cgronlun
7+
ms.service: cognitive-services
8+
ms.component: custom-vision
9+
ms.topic: article
10+
ms.date: 08/07/2018
11+
ms.author: larryfr
12+
# As a developer, I want to use the custom vision REST API to create, train, and export a model
13+
---
14+
# Tutorial: Use the Custom Vision REST API
15+
16+
Learn how to use the Custom Vision REST API to create, train, test, and export a model.
17+
18+
The information in this document demonstrates how to use a REST client to work with the REST API for training the Custom Vision service. The examples show how to use the API using the `curl` utility from a bash environment and `Invoke-WebRequest` from Windows PowerShell.
19+
20+
> [!div class="checklist"]
21+
> * Get keys
22+
> * Create a project
23+
> * Create tags
24+
> * Add images
25+
> * Train and test the model
26+
> * Export the model
27+
28+
## Prerequisites
29+
30+
* A basic familiarity with Representational State Transfer (REST). This document does not go into details on things like HTTP verbs, JSON, or other things commonly used with REST.
31+
32+
* Either a bash (Bourne Again Shell) with the [curl](https://curl.haxx.se) utility or Windows PowerShell 3.0 (or greater).
33+
34+
* A Custom Vision account. For more information, see the [Build a classifier](getting-started-build-a-classifier.md) document.
35+
36+
## Get keys
37+
38+
When using the REST API, you must authenticate using a key. When performing management or training operations, you use the __training key__. When using the model to make predictions, you use the __prediction key__.
39+
40+
When making a request, the key is sent as a request header.
41+
42+
To get the keys for your account, visit the [Custom Vision web page](https://customvision.ai) and select the __gear icon__ in the upper right. In the __Accounts__ section, copy the values from the __Training Key__ and __Prediction Key__ fields.
43+
44+
![Image of the keys UI](./media/rest-api-tutorial/training-prediction-keys.png)
45+
46+
> [!IMPORTANT]
47+
> Since the keys are used to authenticate every request, the examples in this document assume that the key values are contained in environment variables. Use the following commands to store the keys to environment variables before using any other snippets in this document:
48+
>
49+
> ```bash
50+
> read -p "Enter the training key: " TRAININGKEY
51+
> read -p "Enter the prediction key: " PREDICTIONKEY
52+
> ```
53+
>
54+
> ```powershell
55+
> $trainingKey = Read-Host 'Enter the training key'
56+
> $predictionKey = Read-Host 'Enter the prediction key'
57+
> ```
58+
59+
## Create a new project
60+
61+
The following examples create a new project named `myproject` in your Custom Vision service instance. This service defaults to the `General` domain:
62+
63+
```bash
64+
curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects?name=myproject" -H "Training-Key: $TRAININGKEY" --data-ascii ""
65+
```
66+
67+
```powershell
68+
$resp = Invoke-WebRequest -Method 'POST' `
69+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects?name=myproject" `
70+
-UseBasicParsing `
71+
-Headers @{ "Training-Key"="$trainingKey" }
72+
$resp.Content
73+
```
74+
75+
The response to the request is similar to the following JSON document:
76+
77+
```json
78+
{
79+
"id":"45d1b19b-69b6-4a22-8e7e-d1ca37504686",
80+
"name":"myproject",
81+
"description":"",
82+
"settings":{
83+
"domainId":"ee85a72c-405e-4adc-bb47-ffa8ca0c9f31",
84+
"useNegativeSet":true,
85+
"classificationType":"Multilabel",
86+
"detectionParameters":null
87+
},
88+
"created":"2018-08-10T17:39:02.5633333",
89+
"lastModified":"2018-08-10T17:39:02.5633333",
90+
"thumbnailUri":null
91+
}
92+
```
93+
94+
> [!TIP]
95+
> The `id` entry in the response is the ID of the new project. This is used in other examples later in this document.
96+
97+
For more information on this request, see [CreateProject](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a8290).
98+
99+
### Specific domains
100+
101+
To create a project for a specific domain, you can provide the __domain ID__ as an optional parameter. The following examples show how to retrieve a list of available domains:
102+
103+
```bash
104+
curl -X GET "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/domains" -H "Training-Key: $TRAININGKEY" --data-ascii ""
105+
```
106+
107+
```powershell
108+
$resp = Invoke-WebRequest -Method 'GET' `
109+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/domains" `
110+
-UseBasicParsing `
111+
-Headers @{ "Training-Key"="$trainingKey" }
112+
$resp.Content
113+
```
114+
115+
The response to the request is similar to the following JSON document:
116+
117+
```json
118+
[
119+
{
120+
"id": "ee85a74c-405e-4adc-bb47-ffa8ca0c9f31",
121+
"name": "General",
122+
"type": "Classification",
123+
"exportable": false,
124+
"enabled": true
125+
},
126+
{
127+
"id": "c151d5b5-dd07-472a-acc8-15d29dea8518",
128+
"name": "Food",
129+
"type": "Classification",
130+
"exportable": false,
131+
"enabled": true
132+
},
133+
{
134+
"id": "ca455789-012d-4b50-9fec-5bb63841c793",
135+
"name": "Landmarks",
136+
"type": "Classification",
137+
"exportable": false,
138+
"enabled": true
139+
},
140+
...
141+
]
142+
```
143+
144+
For more information on this request, see [GetDomains](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a827d).
145+
146+
The following example demonstrates creating a new project that uses the __Landmarks__ domain:
147+
148+
```bash
149+
curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects?name=myproject&domainId=ca455789-012d-4b50-9fec-5bb63841c793" -H "Training-Key: $TRAININGKEY" --data-ascii ""
150+
```
151+
152+
```powershell
153+
$resp = Invoke-WebRequest -Method 'POST' `
154+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects?name=myproject&domainId=ca455789-012d-4b50-9fec-5bb63841c793" `
155+
-UseBasicParsing `
156+
-Headers @{ "Training-Key"="$trainingKey" }
157+
$resp.Content
158+
```
159+
160+
## Create tags
161+
162+
To tag images, you must use a tag ID. The following example demonstrates how to create a new tag named `cat` and get a tag ID. Replace `{projectId}` with the ID of your project. Use the `name=` parameter to specify the name of the tag:
163+
164+
```bash
165+
curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/tags?name=cat" -H "Training-Key: $TRAININGKEY" --data-ascii ""
166+
```
167+
168+
```powershell
169+
$resp = Invoke-WebRequest -Method 'POST' `
170+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/tags?name=cat" `
171+
-UseBasicParsing `
172+
-Headers @{ "Training-Key"="$trainingKey" }
173+
$resp.Content
174+
```
175+
176+
The response to the request is similar to the JSON document:
177+
178+
```json
179+
{"id":"ed6f7ab6-5132-47ad-8649-3ec42ee62d43","name":"cat","description":null,"imageCount":0}
180+
```
181+
182+
Save the `id` value, as it is used when tagging images.
183+
184+
For more information on this request, see [CreateTag](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a829d).
185+
186+
## Add images
187+
188+
The following examples demonstrate adding a file from URL. Replace `{projectId}` with the ID of your project. Replace `{tagId}` with the ID of the tag for the image:
189+
190+
```bash
191+
curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/images/urls" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii '{"images": [{"url": "http://myimages/cat.jpg","tagIds": ["{tagId}"],"regions": [{"tagId": "{tagId}","left": 119.0,"top": 94.0,"width": 240.0,"height": 140.0}]}], "tagIds": ["{tagId}"]}'
192+
```
193+
194+
```powershell
195+
$resp = Invoke-WebRequest -Method 'POST' `
196+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/images/urls" `
197+
-UseBasicParsing `
198+
-Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" } `
199+
-Body '{"images": [{"url": "http://myimages/cat.jpg","tagIds": ["{tagId}"],"regions": [{"tagId": "{tagId}","left": 119.0,"top": 94.0,"width": 240.0,"height": 140.0}]}], "tagIds": ["{tagId}"]}'
200+
$resp.Content
201+
```
202+
203+
The response to the request is similar to the following JSON document:
204+
205+
```json
206+
{
207+
"isBatchSuccessful": true,
208+
"images": [
209+
{
210+
"sourceUrl": "http://myimages/cat.jpg",
211+
"status": "OK",
212+
"image": {
213+
"id": "081adaee-a76b-4d94-a70e-e4fd0935a28f",
214+
"created": "2018-08-13T13:24:22.0815638",
215+
"width": 640,
216+
"height": 480,
217+
"imageUri": "https://linktoimage",
218+
"thumbnailUri": "https://linktothumbnail",
219+
"tags": [
220+
{
221+
"tagId": "ed6f7ab6-5132-47ad-8649-3ec42ee62d43",
222+
"tagName": null,
223+
"created": "2018-08-13T13:24:22.104936"
224+
}
225+
],
226+
"regions": [
227+
{
228+
"regionId": "40f206a1-3f8a-4de7-a6c3-c7b4643117df",
229+
"tagName": null,
230+
"created": "2018-08-13T13:24:22.104936",
231+
"tagId": "ed6f7ab6-5132-47ad-8649-3ec42ee62d43",
232+
"left": 119,
233+
"top": 94,
234+
"width": 240,
235+
"height": 140
236+
}
237+
]
238+
}
239+
}
240+
]
241+
}
242+
```
243+
244+
For more information on this request, see [CreateImagesFromUrls](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a8287).
245+
246+
## Train the model
247+
248+
The following examples demonstrate how to train the model. Replace `{projectId}` with the ID of your project:
249+
250+
```bash
251+
curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/train" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii ""
252+
```
253+
254+
```powershell
255+
$resp = Invoke-WebRequest -Method 'POST' `
256+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/train" `
257+
-UseBasicParsing `
258+
-Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" }
259+
$resp.Content
260+
```
261+
262+
The response to the request is similar to the following JSON document:
263+
264+
```json
265+
{
266+
"id": "23de09d6-42a1-413e-839e-8db6ee6d3496",
267+
"name": "Iteration 1",
268+
"isDefault": false,
269+
"status": "Training",
270+
"created": "2018-08-10T17:39:02.5766667",
271+
"lastModified": "2018-08-16T17:15:07.5250661",
272+
"projectId": "45d1b19b-69b8-4b22-8e7e-d1ca37504686",
273+
"exportable": false,
274+
"domainId": null
275+
}
276+
```
277+
278+
Save the `id` value, as it is used to test and export the model.
279+
280+
For more information, see [TrainProject](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a8294).
281+
282+
## Test the model
283+
284+
The following examples demonstrate how to perform a test of the model. Replace `{projectId}` with the ID of your project. Replace `{iterationId}` with the ID returned from training the model. Replace `https://linktotestimage` with the path to the test image.
285+
286+
```bash
287+
curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/quicktest/url?iterationId={iterationId}" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii '{"url":"https://linktotestimage"}'
288+
```
289+
290+
```powershell
291+
$resp = Invoke-WebRequest -Method 'POST' `
292+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/quicktest/url?iterationId={iterationId}" `
293+
-UseBasicParsing `
294+
-Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" } `
295+
-Body '{"url":"https://linktotestimage"}'
296+
$resp.Content
297+
```
298+
299+
The response to the request is similar to the following JSON document:
300+
301+
```json
302+
{
303+
"id": "369b010b-2a92-4f48-a918-4c1a0af91888",
304+
"project": "45d1b19b-69b8-4b22-8e7e-d1ca37504686",
305+
"iteration": "23de09d6-42a1-413e-839e-8db6ee6d3496",
306+
"created": "2018-08-16T17:39:20.7944508Z",
307+
"predictions": [
308+
{
309+
"probability": 0.8390652,
310+
"tagId": "ed6f7ab6-5132-47ad-8649-3ec42ee62d43",
311+
"tagName": "cat"
312+
}
313+
]
314+
}
315+
```
316+
317+
For more information, see [QuickTestImageUrl](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a828d).
318+
319+
## Export the model
320+
321+
Exporting a model is a two-step process. First you must specify the model format, and then request the URL for the exported model.
322+
323+
### Request a model export
324+
325+
The following examples demonstrate how to export a `coreml` model. Replace `{projectId}` with the ID of your project. Replace `{iterationId}` with the ID returned from training the model.
326+
327+
```bash
328+
curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/iterations/{iterationId}/export?platform=coreml" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii ''
329+
```
330+
331+
```powershell
332+
$resp = Invoke-WebRequest -Method 'POST' `
333+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/iterations/{iterationId}/export?platform=coreml" `
334+
-UseBasicParsing `
335+
-Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" }
336+
$resp.Content
337+
```
338+
339+
The response to the request is similar to the following JSON document:
340+
341+
```json
342+
{
343+
"platform": "CoreML",
344+
"status": "Exporting",
345+
"downloadUri": null,
346+
"flavor": null
347+
}
348+
```
349+
350+
For more information, see [ExportIteration](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a829b).
351+
352+
### Download the exported model
353+
354+
The following examples demonstrate how to retrieve the URL of the exported model. Replace `{projectId}` with the ID of your project. Replace `{iterationId}` with the ID returned from training the model.
355+
356+
```bash
357+
curl -X GET "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/iterations/{iterationId}/export" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii ''
358+
```
359+
360+
```powershell
361+
$resp = Invoke-WebRequest -Method 'GET' `
362+
-Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/iterations/{iterationId}/export" `
363+
-UseBasicParsing `
364+
-Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" }
365+
$resp.Content
366+
```
367+
368+
The response to the request is similar to the following JSON document:
369+
370+
```json
371+
[
372+
{
373+
"platform": "CoreML",
374+
"status": "Done",
375+
"downloadUri": "https://linktoexportedmodel",
376+
"flavor": null
377+
}
378+
]
379+
```
380+
381+
For more information, see [GetExports](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a829a).

‎articles/cognitive-services/Custom-Vision-Service/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@
2121
href: custom-vision-onnx-windows-ml.md
2222
- name: Run TensorFlow model in Python
2323
href: export-model-python.md
24+
- name: Train a model using the REST API
25+
href: rest-api-tutorial.md
2426
- name: Build apps
2527
items:
2628
- name: Image Classification

0 commit comments

Comments
 (0)