--- schema_version: "1" id: d94c201549bcb0873ed33032a6563ed4b63b0e509d7d577b46ba308adb3ab083 title: Einstein Vision and Language API collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/einstein-vision-language/einstein/references/generated-api-specs/einstein-vision-language.md canonical_url: https://developer.salesforce.com/docs/analytics/einstein-vision-language/references/einstein-vision-language source_site: developer.salesforce.com content_type: documentation content_hash: 0bacd8d599a97cc1a638c2aa0708d317bd9f37ea71f02f2696fa5a4a44936f6b products: - Einstein Vision and Language - Einstein Vision and Language Repo --- Einstein Vision and Language API # Einstein Vision and Language API * * * **Important:** Salesforce is retiring Einstein Vision and Language, and your subscription will not be renewable after May 1, 2024. You can continue using Einstein Vision and Language through your Order Term. To avoid interruptions, transition any Salesforce org using Einstein Vision and Language to another solution before your subscriptions expire. We will be communicating additional details to you soon. If you have questions, contact your Account Executive about your subscriptions. * * * You access the Einstein Vision and Einstein Language services via these standard REST API calls. Use the APIs to programmatically work with datasets, labels, examples, models, and predictions. **Einstein Vision and Language Are HIPAA Compliant** Einstein Vision and Language are Health Insurance Portability and Accountability Act (HIPAA) compliant. Einstein Vision and Language meet the strict HIPAA standards for processing customers' protected health information (PHI). HIPAA compliance positions Einstein Vision and Language services to provide capabilities that can be used in the highly regulated healthcare sector. ### API Error Codes and Messages If an API call is unsuccessful, it returns an HTTP error code. If the error is known, you receive a message in the response body. Known errors are returned in the response body in this format. ```json { "message": "Invalid authentication scheme" } ``` #### All | HTTP Code | HTTP Message | API Message | Resource | Possible Causes | | --- | --- | --- | --- | --- | | 401 | Unauthorized | Invalid access token | Any | The access token is expired. | | 401 | Unauthorized | Invalid authentication scheme | Any | An `Authorization` header was provided, but the token isn't properly formatted. | | 5XX | Internal server error; Service unavailable | None | Any | Our systems encountered and logged an unexpected error. Please contact us if you continue to see the error. | #### Datasets Error codes that can occur when you access datasets, labels, or examples. | HTTP Code | HTTP Message | API Message | Resource | Possible Causes | | --- | --- | --- | --- | --- | | 400 | Bad Request | None | Any dataset, label, or example resources. | The request couldn't be fulfilled because the HTTP request was malformed, the Content Type was incorrect, there were missing parameters, or a parameter was provided with an invalid value. | | 400 | Bad Request | The `name` parameter is required to create a dataset. | `POST /language/datasets` | The `name` parameter was passed in, but no value was provided. | | 400 | Bad Request | Uploading a dataset requires either the `data` field. | `POST /language/datasets/upload` | The path to the local .zip file or the URL to the .zip file in the cloud wasn't specified. | | 400 | Bad Request | The `data` parameter cannot be duplicated. | `POST /language/datasets/upload` | The `data` parameter cannot be duplicated. | | 400 | Bad Request | The dataset is not yet available for update, try again once the dataset is ready. | `PUT /language/datasets//upload` | You're adding examples to a dataset that's currently being created. You must wait for the dataset to become available before you can add examples to it. | | 400 | Bad Request | Failed to download the dataset from the public URL. | `POST /language/datasets/upload`; `POST /language/datasets/upload/sync` | The API can't access the dataset file via the URL provided. When specifying the URL for a .zip file in a cloud drive service like Dropbox, be sure it's a direct file link, not an interactive download page. Example: `https://www.dropbox.com/s/abcdxyz/mountainvsbeach.zip?dl=1`. | | 400 | Bad Request | Supported dataset types: \[image, image-detection, image-multi-label\] | `POST /language/datasets/upload` | The `type` request parameter contains a value that isn't a valid dataset type. | | 400 | Bad Request | Example max size supported is 1024000. | `POST /language/datasets//examples` | The image file being added as an example exceeds the maximum file size of 1 MB. | | 404 | Not Found | None | Any dataset, label, or example resources. | The requested REST resource doesn't exist or you don't have permission to access the resource. | | 404 | Not Found | Unable to find dataset. | `GET /language/datasets/` | You don't have access to the dataset, or the dataset was deleted. | | 404 | Not Found | Unable to find dataset. | `DELETE /language/datasets/` | You don't have access to the dataset, or the dataset was deleted. | | 404 | Bad Request | Duplicate labels are not allowed. | `POST /language/datasets` | The call is trying to create a label with a name that exists in the dataset. Label names must be unique within a dataset. | | 503 | Service Unavailable | Operation timed out! | `GET /language/datasets` | The call has timed out due to large data size. By default, this call returns 25 datasets. If the datasets contain many examples, use the `offset` and `count` parameters to limit and page through the data. | #### Training Error codes that can occur when you train a dataset to create a model or access a model. | HTTP Code | HTTP Message | API Message | Resource | Possible Causes | | --- | --- | --- | --- | --- | | 400 | Bad Request | The `name` parameter is required to train; a valid `datasetId` parameter is required to create an example. | `POST /language/train` | The `name` or `datasetId` parameter was passed in, but no value was provided. | | 400 | Bad Request | The `name` or `datasetId` parameters are required to train. | `POST /language/train` | The `name` or `datasetId` parameter is missing. | | 400 | Bad Request | Invalid id `` | `GET /language/train/` | There's no model with an ID that matches the `modelId` parameter. | | 400 | Bad Request | Invalid id `` | `GET /language/train//lc` | There's no model with an ID that matches the `modelId` parameter. | | 400 | Bad Request | The job has not terminated yet; its current status is RUNNING or QUEUED. | `GET /language/models/` | The model for which you are getting metrics hasn't completed training. | | 404 | Not Found | None | `GET /language/models/` | The `modelId` parameter is missing. | | 405 | Method Not Allowed | None | `GET /language/train/` | The `modelId` parameter is missing. | #### Prediction Error codes that can occur when you make a prediction. | HTTP Code | HTTP Message | API Message | Resource | Possible Causes | | --- | --- | --- | --- | --- | | 400 | Bad Request | None | `POST /language/intent` | The prediction request couldn't be fulfilled because the HTTP request was malformed, the Content Type was incorrect, there were missing parameters, or a parameter was provided with an invalid value. | | 400 | Bad Request | Bad Request: Bad sampleLocation | `POST /language/intent` | The URL passed in the `sampleLocation` parameter is invalid. The URL could be incorrect, contain the wrong file name, or the file may have been moved. | | 400 | Bad Request | The `modelId` parameter is required. | `POST /language/intent` | The `modelId` parameter is missing. | | 400 | Bad Request | File size limit exceeded | `POST /language/intent` | The file you passed in for prediction exceeds the maximum file size limit of 5 MB. | | 400 | Bad Request | Bad Request: Unsupported sample file format | `POST /language/intent` | The file you passed in for prediction isn't one of the supported file types. | | 403 | Forbidden | Forbidden! | `POST /language/intent` | The model specified by the `modelId` parameter doesn't exist; or the `modelId` parameter was passed in but no value was provided. | | 429 | Too Many Requests | You've reached the maximum number of predictions. | `POST /language/intent` | You have exceeded the number of prediction requests for your current plan. Contact your AE to update your plan. See [Rate Limits](https://developer.salesforce.com/docs/analytics/einstein-vision-language/guide/rate-limits.html). | **Version:** 1.0 Contact: Salesforce Einstein, einstein-ep-appservicefoundation@salesforce.com, https://www.einstein.com Terms of service: https://developer.salesforce.com/files/tos/Developerforce\_TOU\_20101119.pdf ## Servers * `https://api.einstein.ai` Default security: bearerAuth. ## Security * `bearerAuth` (http) Use a bearer access token in the `Authorization` header: `Authorization: Bearer `. Obtain access tokens by calling `POST /v2/oauth2/token`. * HTTP scheme: bearer (OAuth 2.0 access token) * `einsteinOAuth2` (oauth2) Einstein Vision and Language issues access tokens from `POST /v2/oauth2/token`. This API accepts form-encoded OAuth token grant parameters such as `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` and `grant_type=refresh_token`. OpenAPI 3.0 does not model the JWT bearer grant exactly, so this scheme documents the token URL and access-token usage. * OAuth flow clientCredentials (tokenUrl: https://api.einstein.ai/v2/oauth2/token) ## Tags ### OAuth Token Generate and delete OAuth tokens with these API calls. ### API Usage Returns prediction usage on a monthly basis for the current calendar month and future months. ### Datasets (Language) Create, get, and delete Einstein Language datasets using these API calls. ### Examples (Language) Create, get, and delete Einstein Language examples using these API calls. ### Training (Language) Train, retrain, and get training status of Einstein Language datasets with these API calls. ### Models (Language) Get Einstein Language models, model metrics, and model learning curves with these API calls. ### Predictions (Language) Resources that return predictions for text input. ### Vision Prediction Get Einstein Language models, model metrics, and model learning curves with these API calls. ## Operations ### GET Get API Usage `GET /v2/apiusage` Operation ID: `getApiUsageV2`. Tags: API Usage. Each `apiusage` object in the response contains plan information for a single calendar month for a single license. If you have a six-month paid plan and you make this call on the first month, the response contains six `apiusage` objects; one for each calendar month in the plan. For more information about plans, see [Rate Limits](https://developer.salesforce.com/docs/analytics/einstein-vision-language/guide/rate-limits.html). This the cURL request for this call. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/apiusage ``` * If you're using the free tier, the response contains plan information only for the current month. You see plan information only after you make your first prediction. If you call the `/apiusage` resource before you make your first prediction call, the API returns an empty array. * If you're using the paid tier, the response contains plan information for each month in your plan starting with the current month. The `planData` array contains an object for each plan type associated with the calendar month and the license. This code snippet shows the `planData` if the user has two Heroku GOLD plans. ```json "planData": [ { "plan": "GOLD", "amount": 2, "source": "HEROKU" } ] ``` #### Responses * **200** API usage Media type: `application/json`. Schema: `ApiUsageList`. * **500** Failed to get usage ### DELETE Delete a Refresh Token `DELETE /v2/oauth2/tokens/{refreshToken}` Operation ID: `deleteRefreshToken`. Tags: OAuth Token. This call doesn't return a response body. Instead, it returns an HTTP status code `204`. This is the cURL request. ```cURL curl -X DELETE -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/oauth2/tokens/ ``` #### Parameters * `Authorization` (header, string) * `refreshToken` (path, string, required) The refresh token to revoke. _Example_ ``` SOME_REFRESH_TOKEN ``` #### Responses * **204** Token is deleted successfully * **400** Bad request ### POST Generate an OAuth Token `POST /v2/oauth2/token` Operation ID: `generateToken`. Tags: OAuth Token. Returns an OAuth access token. You must pass a valid access token in the header of each API call. For information about how to create an access token, see [Generate an OAuth Token Using Your Key](https://developer.salesforce.com/docs/analytics/einstein-vision-language/guide/generate-an-oauth-token-using-your-key.html?q=oauth). For information about how to create a refresh token, see [Generate an OAuth Token Using a Refresh Token](https://developer.salesforce.com/docs/analytics/einstein-vision-language/guide/generate-an-oauth-token-using-a-refresh-token.html?q=oauth). This is the cURL request for generating an access or refresh token. ```cURL // Generate an access token curl -H "Content-type: application/x-www-form-urlencoded" -X POST https://api.einstein.ai/v2/oauth2/token -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=" // Generate a refresh token curl -H "Content-type: application/x-www-form-urlencoded" -X POST https://api.einstein.ai/v2/oauth2/token -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=&scope=offline" ``` #### Request body Media type: `application/x-www-form-urlencoded`. Schema: `object`. * `assertion` (_string_) encrypted payload to identify yourself Example: `SOME_ASSERTION_STRING`. * `scope` (_string_) set to `offline` to generate a refresh token Example: `offline`. * `grant_type` (_string_, required) specify the authentication method desired Allowed values: `urn:ietf:params:oauth:grant-type:jwt-bearer`, `refresh_token`. Example: `urn:ietf:params:oauth:grant-type:jwt-bearer`. * `refresh_token` (_string_) The refresh token you created previously. Example: `SomeRefreshToken`. * `valid_for` (_integer (int32)_) Number of seconds until the access token expires. Default is 60 seconds. Maximum value is 30 days Default: `60`. Example: `120`. #### Responses * **200** Access token result Media type: `application/json`. Schema: `GenerateAccessTokenResponse`. * **400** Bad request ### POST insightJSON `POST /v2/language/analyze` Operation ID: `insightJSON`. Tags: Predictions (Language). #### Request body (required) Conversation turn & historical dialogues Media type: `application/json`. Schema: `ELURequest`. #### Responses * **200** Generate NLU insights Media type: `application/json`. Schema: `ELUResponse`. #### Code samples _Example: cURL · curl_ ``` curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: application/json" -d '{"text":"","locale":"en_US","timeZone":"America/Los_Angeles","context":{"models":[{"id":"","type":"intents","numResults":1}],"dialogue":[{"agent":1,"text":""}]},"agent":1}' "https://api.einstein.ai/v2/language/analyze" ``` ### POST Detect Entities in Text `POST /v2/language/entities` Operation ID: `entitiesMultipart`. Tags: Predictions (Language). The Einstein NER (beta) named-entity recognition (NER) model returns entities for a specified string. **Note:** As a beta feature, Einstein NER is a preview and isn’t part of the “Services” under your Main Services Agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. #### Request Parameters | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `document` | string | Text to classify. Maximum length is 3,000 characters. | 2.0 | | `language` | string | Language of the document parameter. Optional. Valid values: Brazilian Portuguese `pt_BR`; Chinese (Simplified) `zh_CN`; Chinese (Traditional) `zh_TW`; Danish (beta) `da`; Dutch `nl_NL`; English UK `en_GB`; English US `en_US`; French `fr`; German `de`; Italian `it`; Japanese `ja`; Korean (beta) `ko`; Portuguese `pt_PT`; Russian `ru`; Spanish `es`; Swedish (beta) `sv`. | 2.0 | | `modelId` | string | ID of the model. Optional. Defaults to `ENTITIES`. | 2.0 | | `timeZone` | string | Time zone of the returned DATETIME entity. Optional. Defaults to `America/Los_Angeles`. See this list of [tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for valid time zones, and use the TZ database name value from the table. For example, `Africa/Abidjan`. | 2.0 | | `sampleId` | string | String that you can pass in to tag the prediction. Optional. Can be any value, and is returned in the response. | 2.0 | **Note:** As a beta feature, Danish, Korean, and Swedish language support is a preview and isn’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. This is an example of the cURL request with parameters. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "document=Marc Benioff, the CEO of Salesforce, gave the keynote speech at the conference in Paris last week." https://api.einstein.ai/v2/language/entities ``` Keep the following points in mind: * **Response Sort Order**—The entities returned in the response are sorted by the `span` `start` value. This is the start position in the `document` parameter string of the words the the API recognizes as an entity. #### Pass Request Parameters as JSON When you call the NER endpoint, you can specify a Content-Type of `application/json` and pass the request parameters as JSON. ```json { "modelId": "ENTITIES", "language": "en_US", "document": "Marc Benioff, the CEO of Salesforce, gave the keynote speech at the conference in Paris last week." } ``` The cURL call looks like this. _Windows_ ```cURL curl -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" -d "{\"modelId\":\"ENTITIES\", \"language\": \"en_US\", \"document\":\"Marc Benioff, the CEO of Salesforce, gave the keynote speech at the conference in Paris last week.\"}" https://api.einstein.ai/v2/language/entities ``` _Linux_ ```cURL curl -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"modelId":"ENTITIES", "language": "en_US", "document":"Marc Benioff, the CEO of Salesforce, gave the keynote speech at the conference in Paris last week."}' https://api.einstein.ai/v2/language/entities ``` #### Request body Media type: `multipart/form-data`. Schema: `EntitiesPredictRequest`. #### Responses * **200** Prediction result Media type: `application/json`. Schema: `EntitiesPredictResponse`. * **429** Exceed usage limitation Media type: `application/json`. Schema: `PredictionErrorResponse`. ### POST Prediction for Intent `POST /v2/language/intent` Operation ID: `intentMultipart`. Tags: Predictions (Language). Returns an intent prediction for the given string. #### Request Parameters | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `document` | string | Text for which you want to return an intent prediction. | 2.0 | | `modelId` | string | ID of the model that makes the prediction. The model must have been created from a dataset with a type of `text-intent`. | 2.0 | | `numResults` | int | Number of probabilities to return. Optional. If passed, must be a number greater than zero. The response is sorted by `probability` in descending order. For example, if you pass in 3, only the top three `label` and `probability` values are returned. | 2.0 | | `sampleId` | string | String that you can pass in to tag the prediction. Optional. Can be any value, and is returned in the response. | 2.0 | This is an example of the cURL request with parameters. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "modelId=WEQ6PHPBGFYVX5C7QDP6XU3NXY" -F "document=what is the weather in los angeles" https://api.einstein.ai/v2/language/intent ``` Keep the following points in mind when sending text in for prediction: * If you omit the `numResults` parameter, the response returns probabilities for all the labels in the model. #### Passing Parameters as JSON As an alternative to passing the `modelId` and `document` parameters as multipart/form-data fields, you can pass those parameters as JSON. You can pass the JSON directly as a string or reference a file that contains the JSON. This cURL call sends a JSON string into a case routing model for classification. The `Content-Type` has changed to `application/json`. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: application/json" -d "{\"modelId\":\"2ELVAO5BNVGZLBHMYTV7CGD5AY\",\"document\":\"my password stopped working\"}" https://api.einstein.ai/v2/language/intent ``` Here's what the response might look like. ```json { "probabilities": [ { "label": "Password Help", "probability": 0.99040705 }, { "label": "Order Change", "probability": 0.003532466 }, { "label": "Shipping Info", "probability": 0.003473858 }, { "label": "Billing", "probability": 0.0024010758 }, { "label": "Sales Opportunity", "probability": 0.00018560764 } ], "object": "predictresponse" } ``` You can store the JSON in a file and reference that file. For example, the file intent.json might look like the following. ```json { "modelId": "2ELVAO5BNVGZLBHMYTV7CGD5AY", "document": "my password stopped working" } ``` This cURL call references that file. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: application/json" -d @c:\data\intent.json https://api.einstein.ai/v2/language/intent ``` ##### Rate Limit Headers Any time you make an API call to the `/intent` resource, your rate limit information is returned in the header. The rate limit headers specify your prediction usage for the current calendar month only. ```text X-RateLimit-Limit 2000 X-RateLimit-Remaining 1997 X-RateLimit-Reset 2017-04-01 19:31:42.0 ``` | Header | Description | Example | | --- | --- | --- | | `X-RateLimit-Limit` | Maximum number of prediction calls available for the current plan month. | 2000 | | `X-RateLimit-Remaining` | Total number of prediction calls you have left for the current plan month. | 1997 | | `X-RateLimit-Reset` | Date on which your predictions are next provisioned. Always the first of the month. | 2017-04-01 22:07:40.0 | #### Request body Media type: `multipart/form-data`. Schema: `IntentPredictRequest`. Media type: `application/json`. Schema: `IntentPredictRequest`. #### Responses * **200** Prediction result Media type: `application/json`. Schema: `IntentPredictResponse`. * **400** Bad request * **404** Not found * **429** Exceed usage limitation Media type: `application/json`. Schema: `PredictionErrorResponse`. ### POST Prediction for Sentiment `POST /v2/language/sentiment` Operation ID: `sentimentMultipart`. Tags: Predictions (Language). Returns a sentiment prediction for the given string. #### Request Parameters | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `document` | string | Text for which you want to return a sentiment prediction. | 2.0 | | `modelId` | string | ID of the model that makes the prediction. The model must have been created from a dataset with a type of `text-sentiment`. | 2.0 | | `numResults` | int | Number of probabilities to return. Optional. If passed, must be a number greater than zero. The response is sorted by `probability` in descending order. For example, if you pass in 3, only the top three `label` and `probability` values are returned. | 2.0 | | `sampleId` | string | String that you can pass in to tag the prediction. Optional. Can be any value, and is returned in the response. | 2.0 | This is an example of the cURL request with parameters. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "modelId=WJH4YCA7YX4PCWVNCYNWYHBMY4" -F "document=I can't tell you how much fun it was" https://api.einstein.ai/v2/language/sentiment ``` Keep the following points in mind when sending text in for prediction: * If you omit the `numResults` parameter, the response returns probabilities for all the labels in the model. #### Passing Parameters as JSON As an alternative to passing the `modelId` and `document` parameters as multipart/form-data fields, you can pass those parameters as JSON. You can pass the JSON directly as a string or reference a file that contains the JSON. This cURL call sends a JSON string into the prebuilt sentiment model for classification. The `Content-Type` has changed to `application/json`. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: application/json" -d "{\"modelId\":\"CommunitySentiment\",\"document\":\"The presentation was great and I learned a lot\"}" https://api.einstein.ai/v2/language/sentiment ``` Here's what the response might look like. ```json { "probabilities": [ { "label": "positive", "probability": 0.8673582 }, { "label": "negative", "probability": 0.1316828 }, { "label": "neutral", "probability": 0.0009590242 } ], "object": "predictresponse" } ``` You can store the JSON in a file and reference that file. For example, the file sentiment.json might look like the following. ```json { "modelId": "CommunitySentiment", "document": "The presentation was great and I learned a lot" } ``` This cURL call references that file. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: application/json" -d @c:\data\sentiment.json https://api.einstein.ai/v2/language/sentiment ``` ##### Rate Limit Headers Any time you make an API call to the `/sentiment` resource, your rate limit information is returned in the header. The rate limit headers specify your prediction usage for the current calendar month only. ```text X-RateLimit-Limit 2000 X-RateLimit-Remaining 1997 X-RateLimit-Reset 2017-04-01 19:31:42.0 ``` | Header | Description | Example | | --- | --- | --- | | `X-RateLimit-Limit` | Maximum number of prediction calls available for the current plan month. | 2000 | | `X-RateLimit-Remaining` | Total number of prediction calls you have left for the current plan month. | 1997 | | `X-RateLimit-Reset` | Date on which your predictions are next provisioned. Always the first of the month. | 2017-04-01 22:07:40.0 | #### Request body Media type: `multipart/form-data`. Schema: `SentimentPredictRequest`. Media type: `application/json`. Schema: `SentimentPredictRequest`. #### Responses * **200** Prediction result Media type: `application/json`. Schema: `SentimentPredictResponse`. * **400** Bad request * **404** Not found * **429** Exceed usage limitation Media type: `application/json`. Schema: `PredictionErrorResponse`. ### GET Get a Dataset `GET /v2/language/datasets/{datasetId}` Operation ID: `getDataset`. Tags: Datasets (Language). Returns a single dataset. #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` SomeDatasetId ``` #### Responses * **200** Success Media type: `application/json`. Schema: `Dataset`. * **404** Not found #### Code samples _Example: cURL · curl_ ``` curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/language/datasets/" ``` ### DELETE Delete a Dataset `DELETE /v2/language/datasets/{datasetId}` Operation ID: `deleteDataset`. Tags: Datasets (Language). Deletes the specified text dataset and its labels and examples. This is an example of the cURL request. ```cURL curl -X DELETE -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/language/datasets/10008 ``` Keep the following points in mind when deleting a dataset. * If a dataset is being trained and has an associated model with a status of `QUEUED` or `RUNNING`, you must wait until the training is complete before you can delete the dataset. * If you want to delete a dataset and the models associated with it, delete the models first. Deleting a dataset doesn't delete the models created from that dataset. After you delete a dataset, you can still make predictions against the associated models, but you lose the ability to list the models for the deleted dataset. **Important:** As of August 14, 2023 Get Deletion Status has been deprecated and will no longer be supported by Salesforce. Deletion is now immediate. To determine if the a dataset has been deleted use the Get Dataset command. A deleted dataset will return a 404 (Not Found) http status. * After you delete a dataset, use the `id` to get the status of the deletion. See Get Deletion Status. #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` SomeDatasetId ``` #### Responses * **200** Success, deletion job created Media type: `application/json`. Schema: `DeletionResponse`. * **404** Not found ### GET Get All Examples `GET /v2/language/datasets/{datasetId}/examples` Operation ID: `getExamples`. Tags: Examples (Language). Returns all the examples for the specified dataset. This is an example of the cURL request. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/language/datasets/57/examples ``` #### Page Through Examples By default, this call returns 100 examples. If you want to page through the examples in a dataset, use the `offset` and `count` query parameters. | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `count` | int | Number of examples to return. Maximum valid value is 100. If you specify a number greater than 100, the call returns 100 examples. Optional. | 1.0 | | `offset` | int | Index of the example from which you want to start paging. Optional. | 1.0 | Here's an example of these query parameters. If you omit the `count` parameter or the `count` parameter is greater than 100, the API returns 100 examples. If you omit the `offset` parameter, paging starts at 0. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/language/datasets/57/examples?offset=100&count=50" ``` ##### How Paging Works To page through all the examples in a dataset: 1. Make the Get a Dataset call to return the `totalExamples` value for the dataset. 2. Make the Get All Examples call and pass in the `offset` and `count` values until you reach the end of the examples. For example, let's say you have a dataset and you want to display information about the examples in a UI and show 15 at a time. The first call would have `offset=0` and `count=15`, the second call would have `offset=15` and `count=15`, and so on. #### Return Specific Example Types Use the `source` query parameter to return examples that were created in the dataset. * `all`—Return upload examples. * `upload`—Return examples that were created from uploading a file. #### Limits Each Einstein Vision and Language account is limited to 30 calls per calendar month to Einstein Language endpoints that return examples. This limit applies across all APIs that return examples. If you exceed this limit, you receive an error message. See [Release Notes](https://developer.salesforce.com/docs/analytics/einstein-vision-language/guide/release-notes-einstein-platform-services.html). #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` SomeDatasetId ``` * `offset` (query, integer (int32)) Index of the example from which you want to start paging. Default: `0`. * `count` (query, integer (int32)) Number of examples to return. Default: `100`. * `source` (query, string) return examples that were created in the dataset Allowed values: `all`, `upload`. #### Responses * **200** Success Media type: `application/json`. Schema: `ExampleList`. * **400** Bad request * **404** Dataset not found ### GET Get All Examples for Label `GET /v2/language/examples/{datasetId}/label/{labelId}` Operation ID: `getExamplesByLabel`. Tags: Predictions (Language). Returns all the examples for the specified label. Returns uploaded examples. **NOTE:** This is a new endpoint. Use this updated endpoint after December 3, 2020 to get all examples for a label. This is an example of the cURL request. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/language/examples/1000108/label/16599 ``` #### Page Through Examples By default, this call returns 100 examples. If you want to page through all the examples returned by this call, use the `offset` and `count` query parameters. The `numExamples` value indicates how many examples have the specified label, so you can use this value to control the paging. | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `count` | int | Number of examples to return. Maximum valid value is 100. If you specify a number greater than 100, the call returns 100 examples. Optional. | 1.0 | | `offset` | int | Index of the example from which you want to start paging. Optional. | 1.0 | The following call shows how to page through examples using these query parameters. If you omit the `count` parameter or the `count` parameter is greater than 100, the API returns 100 examples. If you omit the `offset` parameter, paging starts at 0. When using multiple query parameters in a cURL call, be sure to enclose the endpoint in quotes. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/language/examples/7890/label/1234?offset=50&count=50" ``` **Note:** This call returns uploaded examples that have the specified label. This call doesn't support the `source` parameter. #### Limits Each Einstein Vision and Language account is limited to 30 calls per calendar month to Einstein Language endpoints that return examples. This limit applies across all APIs that return examples. If you exceed this limit, you receive an error message. See [Release Notes](https://developer.salesforce.com/docs/analytics/einstein-vision-language/guide/release-notes-einstein-platform-services.html). #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` SomeDatasetId ``` * `labelId` (path, integer (int32), required) Label Id _Example_ ``` SomeLabelId ``` * `offset` (query, integer (int32)) Index of the example from which you want to start paging. Default: `0`. * `count` (query, integer (int32)) Number of examples to return. Default: `100`. #### Responses * **200** Success Media type: `application/json`. Schema: `ExampleList`. * **400** Bad request * **404** Dataset not found ### GET Get All Models `GET /v2/language/datasets/{datasetId}/models` Operation ID: `getTrainedModels`. Tags: Models (Language). Returns all models for the specified dataset. This is an example of the cURL request. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/language/datasets/1001511/models ``` #### Page Through Models By default, this call returns 100 models. If you want to page through your models, use the `offset` and `count` query parameters. | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `count` | int | Number of models to return. Maximum valid value is 100. If you specify a number greater than 100, the call returns 100 models. Optional. | 1.0 | | `offset` | int | Index of the dataset from which you want to start paging. Optional. | 1.0 | Here's an example of these query parameters. If you omit the `offset` parameter, paging starts at 0. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/language/datasets//models?offset=5&count=5" ``` #### Parameters * `offset` (query, integer (int32)) Index of the model from which you want to start paging. Default: `0`. * `count` (query, integer (int32)) Number of models to return. Default: `100`. * `datasetId` (path, string, required) Dataset Id _Example_ ``` SomeDatasetId ``` #### Responses * **200** Success Media type: `application/json`. Schema: `ModelList`. * **404** Not found ### GET Get All Datasets `GET /v2/language/datasets` Operation ID: `listDatasets`. Tags: Datasets (Language). Returns a list of datasets and their labels that were created by the current user. The response is sorted by dataset ID. This is an example of the cURL request. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/language/datasets ``` #### Page Through Datasets By default, this call returns 25 datasets. If you want to page through your datasets, use the `offset` and `count` query parameters. | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `count` | integer | Number of datsets to return. Maximum valid value is 25. If you specify a number greater than 25, the call returns 25 datasets. Optional. | 2.0 | | `offset` | integer | Index of the dataset from which you want to start paging. Optional. | 2.0 | Here's an example of these query parameters. If you omit the `count` parameter, the API returns 25 datasets. If you omit the `offset` parameter, paging starts at 0. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/language/models/TUWBAIRLFB3KKEDZMEGIUR6COM/lc?offset=100&count=20" ``` For example, let's say you want to page through all of your datasets and show 20 at a time. The first call would have `offset=0` and `count=20`, the second call would have `offset=20` and `count=20`, and so on. #### Get Global Datasets Global datasets are public datasets that Salesforce provides. You can use these datasets to include additional data during training when you create a model. To get a list of the global datasets, use the `global` query parameter. | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `global` | boolean | If `true`, returns all global datasets. | 2.0 | Here's an example of the `global` query parameter. The response JSON is the same as for your own custom datasets. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/language/datasets?global=true" ``` #### Parameters * `count` (query, integer (int32)) Number of datsets to return. Maximum valid value is 25. If you specify a number greater than 25, the call returns 25 datasets. Default: `25`. * `offset` (query, integer (int32)) Index of the dataset from which you want to start paging Default: `0`. * `global` (query, boolean) If true, returns all global datasets. Global datasets are public datasets that Salesforce provides. Default: `false`. #### Responses * **200** Success Media type: `application/json`. Schema: `DatasetList`. ### PUT Create Examples From a File `PUT /v2/language/datasets/{datasetId}/upload` Operation ID: `updateDatasetAsync`. Tags: Examples (Language). Adds examples from a .csv, .tsv, or .json file to a dataset. #### Request Parameters | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `data` | string | Path to the .csv, .tsv, or .json file on a local drive. The maximum file size you can upload from a local drive is 25 MB. | 2.0 | Here's an example of the cURL request with parameters. ```cURL // Add examples to a dataset from a local file curl -X PUT -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "data=@C:\Data\weather_update.csv" https://api.einstein.ai/v2/language/datasets/1001412/upload ``` This call adds examples to the specified dataset from a .csv, .tsv, or .json file. This is an asynchronous call, so the results that are initially returned contain information for the original dataset and `available` is `false`. Use the dataset ID and use Get a Dataset to query when the upload is complete. When `available` is `true` and `statusMsg` is `SUCCEEDED`, the data upload is complete. Each dataset type supports different file formats. This table lists the file formats supported by each dataset type. | | text-intent | text-sentiment | | --- | --- | --- | | **.csv file** | Y | Y | | **.tsv file** | Y | Y | | **.json file** | Y | N | Keep the following tipd in mind when you create examples: **FILE SIZE** * The maximum file size you can upload from a local drive is 25 MB. **DATASETS** * The maximum total dataset size is 2 GB. **LABELS** * If the file contains a label that's already in the dataset, the API adds the sentiment or intent strings (examples) with the specified label in the dataset. * If the file contains a label that isn't in the dataset, the API adds a new label (label name limit is 180 characters). **EXAMPLES** * A dataset can have a maximum of 3 million words across all examples. If you try to train a dataset that has more than 3 million words, you receive an error. * For best results, we recommend that each example is around 100 words. **OTHER** * The Einstein Language APIs support only UTF-8 text characters. If your examples or labels contain any non-UTF-8 text, you receive an error that the file format is invalid when you try to create the examples. * If you try to create examples in a dataset while a previous call to create examples is still processing (the dataset's `available` value is `false`), the call fails and you receive an error. You must wait until the dataset's `available` value is `true` before starting another upload. See Create a Dataset From a File Asynchronously or Create a Dataset From a File Synchronously for information about the file structure. #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` SomeDatasetId ``` #### Request body Media type: `multipart/form-data`. Schema: `object`. * `data` (_string_) Path to the .csv, .tsv, or .json file on a local drive. * `path` (_string_) URL of the .csv, .tsv, or .json file. * `type` (_string_) Path of the .csv, .tsv, or .json file. #### Responses * **200** Upload success Media type: `application/json`. Schema: `Dataset`. ### POST Create a Dataset From a File Asynchronously `POST /v2/language/datasets/upload` Operation ID: `uploadDatasetAsync`. Tags: Datasets (Language). Creates a dataset, labels, and examples from the specified .csv, .tsv, or .json file. The call returns immediately and continues to upload data in the background. #### Request Parameters | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `data` | string | Path to the .csv, .tsv, or .json file on the local drive (FilePart). The maximum file size you can upload from a local drive is 25 MB. | 2.0 | | `language` | string | (Optional) Dataset language. Default is `en_US`. See [Supported Languages](https://developer.salesforce.com/docs/analytics/einstein-vision-language/guide/supported-languages.html?q=supported%20languages). | 2.0 | | `name` | string | (Optional) Name of the dataset. If this parameter is omitted, the dataset name is derived from the file name. | 2.0 | | `type` | string | Type of dataset data. Valid values are `text-intent` and `text-sentiment`. | 2.0 | Here's an example of the cURL request with parameters. ```cURL // Create a dataset from a local file curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "data=@C:\Data\weather.csv" -F "type=text-intent" https://api.einstein.ai/v2/language/datasets/upload ``` The API call is asynchronous, so you receive a dataset ID back immediately but the `available` value is `false` and the `statusMsg` value is `UPLOADING`. Use the dataset ID and make a call to Get a Dataset to query when the upload is complete. When `available` is `true` and `statusMsg` is `SUCCEEDED`, the data upload is complete, and you can train the dataset to create a model. Keep the following points in mind when creating datasets. **FILE SIZE** * The maximum file size you can upload from a local drive or web location is 25 MB. * If your file is more than 20 MB, for better performance, we recommend that you upload it to a cloud location that doesn't require authentication and pass the URL in the `path` parameter. * If you have a large amount of data, consider breaking up your data into multiple files. You can load the first file using this call and then load subsequent files using PUT. See Create Examples From a File. **DATASETS** * The maximum total dataset size is 2 GB. **LABELS** * The maximum label name length is 180 characters. If a file contains a class label name greater than 180 characters, the label is created in the dataset, but the API truncates the label name to 180 characters. * You must have at least two labels in the dataset. If you don't have at least two labels, you can create the dataset but training the dataset fails. * A dataset can have up to 500 labels. However, we recommend that a dataset has a maximum of 100 labels for better model accuracy. **EXAMPLES** * If a file contains duplicate intent or sentiment strings, only the first one is loaded. * If the dataset type is `text-intent`, each label must have at least 20 examples. We recommend that each label has at least 100 examples for better model accuracy. If you have only 20 examples, be sure to use the `multilingual-intent` or `multilingual-intent-ood` algorithm when you train the dataset. * If the dataset type is `text-sentiment`, each label must have at least 100 examples. * We recommend a maximum of 10,000 examples across all labels. * A dataset can have a maximum of 3 million words across all examples. If you try to train a dataset that has more than 3 million words, you receive an error. * For best results, we recommend that each example is less than 150 words. * If the file contains duplicate text strings (examples), only the first string is uploaded. If there's more than one text string with the same text, only the first string is uploaded and the others are skipped. This is true whether the duplicate text strings have the same label or different labels. **OTHER** * The Einstein Language APIs support only UTF-8 text characters. If your examples or labels contain any non-UTF-8 text, you receive an error that the file format is invalid when you try to create the dataset. Each dataset type supports different file formats. This table lists the file formats supported by each dataset type. | | text-intent | text-sentiment | | --- | --- | --- | | **.csv file** | Y | Y | | **.tsv file** | Y | Y | | **.json file** | Y | N | #### CSV File Format Considerations * You can use a .csv file to create both intent and sentiment datasets. * When you create a dataset from a .csv file, the dataset name is inherited from the file name. * Each .csv file contains sentiment or intent data in this format: `"sentiment or intent string", label-name` followed by a CRLF. In the following example, the intent string is in double quotes followed by the label `current-weather`. ```text "what's the weather look like",current-weather "is it raining",current-weather "what's the temperature",current-weather ``` #### TSV File Format Considerations * You can use a .tsv file to create both intent and sentiment datasets. * When you create a dataset from a .tsv file, the dataset name is inherited from the file name. * Each .tsv file contains sentiment or intent data in this format: `"sentiment or intent string"label-name` followed by a CRLF. In the following example, the intent string is in double quotes followed by the label `current-weather`. ```text "what's the weather look like" current-weather "is it raining" current-weather "what's the temperature" current-weather ``` #### JSON File Format Considerations * You can use a .json file to create only an intent dataset. * The top-level object must be called `"intents"` as shown in the example file. * When you create a dataset from a .json file, the dataset name is inherited from the file name. * The JSON structure is a top-level object that contains multiple arrays. Each array contains the intent strings in double quotes. This image shows the structure of the JSON file. The labels are `current-weather`, `five-day-forecast`, and `hourly-forecast`. The content in double quotes becomes a single example that has the specified label. #### Request body Media type: `multipart/form-data`. Schema: `object`. * `data` (_string_) Path to the .csv, .tsv, or .json file on the local drive (FilePart). * `name` (_string_) Name of the dataset. Optional. If this parameter is omitted, the dataset name is derived from the file name. Default: `dataset`. Example: `weather`. * `path` (_string_) URL of the .csv, .tsv, or .json file. * `language` (_string_) dataset language Default: `en_US`. * `type` (_string_, required) Type of dataset data. Allowed values: `text-intent`, `text-sentiment`. * `entityName` (_string_) Entity name, optional. Minimum length: 0. Maximum length: 180. * `entityFilter` (_string_) Entity filter, optional. Minimum length: 0. Maximum length: 4096. #### Responses * **200** Upload initiated Media type: `application/json`. Schema: `Dataset`. * **400** Bad request ### POST Create a Dataset From a File Synchronously `POST /v2/language/datasets/upload/sync` Operation ID: `uploadDatasetSync`. Tags: Datasets (Language). Creates a dataset, labels, and examples from the specified .csv, .tsv, or .json file. The call returns after the dataset is created and all of the data is uploaded. Use this API call for files that are smaller than 10 MB. ## Request Parameters | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `data` | string | Path to the .csv, .tsv, or .json file on the local drive (FilePart). The maximum file size you can upload from a local drive is 25 MB. | 2.0 | | `language` | string | (Optional) Dataset language. Default is `en_US`. See [Supported Languages](https://developer.salesforce.com/docs/analytics/einstein-vision-language/guide/supported-languages.html?q=supported%20languages). | 2.0 | | `name` | string | (Optional) Name of the dataset. If this parameter is omitted, the dataset name is derived from the file name. | 2.0 | | `type` | string | Type of dataset data. Valid values are: `text-intent` and `text-sentiment` | 2.0 | Here's an example of the cURL request with parameters. ```cURL // Create a dataset from a local file curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "data=@C:\Data\weather.csv" -F "type=text-intent" https://api.einstein.ai/v2/language/datasets/upload/sync ``` The API call is synchronous, so results are returned after the data has been uploaded to the dataset. If this call succeeds, it returns the `labels` array, `available` is `true`, and `statusMsg` is `SUCCEEDED`. Keep the following points in mind when creating datasets. **FILE SIZE** * The maximum file size you can upload from a local drive or web location is 25 MB. * If your file is larger than 10 MB, we recommend that you use the asynchronous call to create a dataset. If you use this call with a large dataset .zip file, the call could time out. See Create a Dataset From a File Asynchronously. * If you have a large amount of data, consider breaking up your data into multiple files. You can load the first file using this call and then load subsequent files using PUT. See Create Examples From a File. **DATSETS** * The maximum total dataset size is 2 GB. **LABELS** * The maximum label name length is 180 characters. If a file contains a class label name greater than 180 characters, the label is created in the dataset, but the API truncates the label name to 180 characters. * You must have at least two labels in the dataset. If you don't have at least two labels, you can create the dataset but training the dataset fails. * A dataset can have up to 500 labels. However, we recommend that a dataset has a maximum of 100 labels for better model accuracy. **EXAMPLES** * If a file contains duplicate intent or sentiment strings, only the first one is loaded. * If the dataset type is `text-intent`, each label must have at least 20 examples. We recommend that each label has at least 100 examples for better model accuracy. If you have only 20 examples, be sure to use the `multilingual-intent` or `multilingual-intent-ood` algorithm when you train the dataset. * If the dataset type is `text-sentiment`, each label must have at least 100 examples. * We recommend a maximum of 10,000 examples across all labels. * A dataset can have a maximum of 3 million words across all examples. If you try to train a dataset that has more than 3 million words, you receive an error. * For best results, we recommend that each example is less than 150 words. \-If the file contains duplicate text strings, only the first string is uploaded. If there's more than one text string with the same text, only the first string is uploaded and the others are skipped. This is true whether the duplicate text strings have the same label or different labels. **OTHER** * The Einstein Language APIs support only UTF-8 text characters. If your examples or labels contain any non-UTF-8 text, you receive an error that the file format is invalid when you try to create the dataset. Each dataset type supports different file formats. This table lists the file formats supported by each dataset type. | | text-intent | text-sentiment | | --- | --- | --- | | **.csv file** | Y | Y | | **.tsv file** | Y | Y | | **.json file** | Y | N | #### CSV File Format Considerations * You can use a .csv file to create both intent and sentiment datasets. * When you create a dataset from a .csv file, the dataset name is inherited from the file name. * Each .csv file contains sentiment or intent data in this format: `"sentiment or intent string", label-name` followed by a CRLF. In the following example, the intent string is in double quotes followed by the label `current-weather`. ```text "what's the weather look like",current-weather "is it raining",current-weather "what's the temperature",current-weather ``` #### TSV File Format Considerations * You can use a .tsv file to create both intent and sentiment datasets. * When you create a dataset from a .tsv file, the dataset name is inherited from the file name. * Each .tsv file contains sentiment or intent data in this format: `"sentiment or intent string"label-name` followed by a CRLF. In the following example, the intent string is in double quotes followed by the label `current-weather`. ```text "what's the weather look like" current-weather "is it raining" current-weather "what's the temperature" current-weather ``` #### JSON File Format Considerations * You can use a .json file to create only an intent dataset. * The top-level object must be called `"intents"` as shown in the example file. * When you create a dataset from a .json file, the dataset name is inherited from the file name. * The JSON structure is a top-level object that contains multiple arrays. Each array contains the intent strings in double quotes. This image shows the structure of the JSON file. The labels are `current-weather`, `five-day-forecast`, and `hourly-forecast`. The content in double quotes becomes a single example that has the specified label. #### Request body Media type: `multipart/form-data`. Schema: `object`. * `data` (_string_) Path to the .csv, .tsv, or .json file on the local drive (FilePart). * `name` (_string_) Name of the dataset. Optional. If this parameter is omitted, the dataset name is derived from the file name. Example: `weather`. * `path` (_string_) URL of the .csv, .tsv, or .json file. * `language` (_string_) dataset language Default: `en_US`. * `type` (_string_) Type of dataset data. Allowed values: `text-intent`, `text-sentiment`. #### Responses * **200** Upload success Media type: `application/json`. Schema: `Dataset`. * **400** Bad request ### GET Get Model Metrics `GET /v2/language/models/{modelId}` Operation ID: `getTrainedModelMetrics`. Tags: Models (Language). Returns the metrics for a model, such as the f1 score, accuracy, and confusion matrix. The combination of these metrics gives you a picture of model accuracy and how well the model will perform. This call returns the metrics for the last epoch in the training used to create the model. This is an example of the cURL request. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/language/models/TUWBAIRLFB3KKEDZMEGIUR6COM ``` Keep the following points in mind when analyzing the precision-recall metrics. * The precision-recall curve arrays are calculated using the examples in the test set (as specified by the `trainSplitRatio`). The margin of error when these values are computed depends on the number of examples in the test set. * The granularity of the threshold variations depends on the number of examples in the test set and the number of labels in the dataset from which the model was created. * The maximum number of values returned in any one of these arrays is 2,000. #### Parameters * `modelId` (path, string, required) Model Id _Example_ ``` SomeModelId ``` #### Responses * **200** Model metrics Media type: `application/json`. Schema: `Metrics`. * **404** Resource not found * **502** Unable to complete request due to service error ### DELETE Delete a Model `DELETE /v2/language/models/{modelId}` Operation ID: `deleteModel`. Tags: Models (Language). Deletes the specified model. After you delete a model, you can use the `id` to get the status of the deletion. See Get Deletion Status. This is an example of the cURL request. ```cURL curl -X DELETE -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/language/models/KD33Y2UZHI2TDB7VXQSUHZBNGA ``` #### Parameters * `modelId` (path, string, required) Model Id _Example_ ``` SomeModelId ``` #### Responses * **201** Deletion submitted Media type: `application/json`. Schema: `DeletionResponse`. * **404** Resource not found * **502** Unable to complete request due to service error ### GET Get Training Status `GET /v2/language/train/{modelId}` Operation ID: `getTrainStatusAndProgress`. Tags: Training (Language). Returns the status of a training job. Use the progress field to determine how far the training has progressed. When training completes successfully, the `status` is `SUCCEEDED` and the `progress` is `1`. This is an example of the cURL request. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" https://api.einstein.ai/v2/language/train/TUWBAIRLFB3KKEDZMEGIUR6COM ``` #### Parameters * `modelId` (path, string, required) Model Id _Example_ ``` SomeModelId ``` #### Responses * **200** Training status Media type: `application/json`. Schema: `TrainResponse`. * **400** Bad request * **404** Resource not found * **502** Unable to complete request due to service error ### GET Get Model Learning Curve `GET /v2/language/models/{modelId}/lc` Operation ID: `getTrainedModelLearningCurve`. Tags: Models (Language). Returns the metrics for each epoch in a model. These metrics show you the f1 score, accuracy, confusion matrix, test accuracy, and so on for each training iteration performed to create the model. This is an example of the cURL request. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/language/models/TUWBAIRLFB3KKEDZMEGIUR6COM/lc?offset=0&count=3" ``` Use the `labels` array and the `confusionMatrix` array to build the confusion matrix for an epoch. The labels in the array become the matrix rows and columns. Here's what the confusion matrix for the first epoch in the results. | | hourly-forecast | current-weather | five-day-forecast | | --- | --- | --- | --- | | **hourly-forecast** | 0 | 2 | 1 | | **current-weather** | 0 | 8 | 0 | | **five-day-forecast** | 0 | 1 | 0 | #### Page Through Results By default, this call returns learning curve data for 25 epochs. If you want to page through the results, use the `offset` and `count` query parameters. | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `count` | int | Number of epochs for which to return metrics. Maximum valid value is 25. If you specify a number greater than 25, the call returns metrics for 25 epochs. Optional. | 2.0 | | `offset` | int | Index of the epoch from which you want to start paging. Optional. | 2.0 | Here's an example of these query parameters. If you omit the `count` parameter, the API returns 25 epochs. If you omit the `offset` parameter, paging starts at 0. ```cURL curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/language/datasets?offset=100&count=20" ``` For example, let's say you want to page through all of the learning curve results and show 20 at a time. The first call would have `offset=0` and `count=20`, the second call would have `offset=20` and `count=20`, and so on. If you want to find out the total number of epochs that were performed to create a model, make the call the get the training status and use the `lastEpochDone` value. This value will give you an idea of how much paging you need to do. See Get Training Status. #### Parameters * `modelId` (path, string, required) Model Id _Example_ ``` SomeModelId ``` * `offset` (query, integer (int32)) Index of the epoch from which you want to start paging Default: `0`. * `count` (query, integer (int32)) Number of epoch to return. Maximum valid value is 25. Default: `25`. #### Responses * **200** Learning curve Media type: `application/json`. Schema: `LearningCurveList`. * **404** Resource not found * **502** Unable to complete request due to service error ### POST Retrain a Dataset `POST /v2/language/retrain` Operation ID: `retrain`. Tags: Training (Language). Retrains a dataset and updates a model. Use this API call when you want to update a model and keep the model ID instead of creating a new model. #### Request Parameters | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `algorithm` | string | Specifies the algorithm used to train the dataset. Optional. Use this parameter only when training a dataset with a type of `text-intent`. Valid values are `intent` (same as `multilingual-intent`, retained for backward compatibility), `multilingual-intent` (supports multiple languages), and `multilingual-intent-ood` (supports multiple languages and handles out-of-domain text). | 2.0 | | `epochs` | int | Number of training iterations for the neural network. Optional. If not specified, the default is calculated based on the dataset size. The larger the number, the longer the training takes to complete. The training process stops before the specified number of epochs if the model has reached the optimal accuracy. When you get the training staus, the `earlyStopping` field specifies whether the training stopped early, and the `lastEpochDone` value specifies the last training iteration. | 2.0 | | `learningRate` | float | N/A for intent or sentiment models. | 2.0 | | `modelId` | string | ID of the model to be used from the training. | 2.0 | | `trainParams` | object | JSON that contains parameters that specify how the model is created. Optional. Valid values include `{"trainSplitRatio": 0.n}` to specify the ratio of data used to train and test the model, and `{"withGlobalDatasetId": }` to use a global dataset in addition to the specified dataset. | 2.0 | This is an example of the cURL request with parameters. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "modelId=TUWBAIRLFB3KKEDZMEGIUR6COM" https://api.einstein.ai/v2/language/retrain ``` This call retrains the dataset associated with model you specify in the request parameters. Use this call to retrain a dataset and update the model after new examples are added to a dataset. To find out the values specified in the `trainParams` parameter when the model was trained, such as `withGlobalDatasetId`, see Get Training Status. Keep the following points in mind when training a dataset: * A dataset can have only one training in progress at a time. Let's say you retrain a dataset and there's a model with a status of `RUNNING` or `QUEUED`. If you attempt to retrain the same dataset again, you receive an error. * You receive an error when you train a dataset that has more than 3 million words across all examples. Be sure that when you create a dataset or add examples to a dataset, that it contains less than 3 million words. For best results, we recommend that each example is around 100 words. This cURL command sends in the `trainParams` request parameter. This command has double quotes and escaped double quotes around `trainSplitRatio` to run on Windows. You might need to reformat it to run on another OS. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "modelId=TUWBAIRLFB3KKEDZMEGIUR6COM" -F "trainParams={\"trainSplitRatio\":0.7}" https://api.einstein.ai/v2/language/retrain ``` #### Request body Media type: `multipart/form-data`. Schema: `object`. * `modelId` (_string_, required) ID of the model to be updated from the training. Example: `7JXCXTRXTMNLJCEF2DR5CJ46QU`. * `epochs` (_integer (int32)_) Number of training iterations for the neural network. Optional. Minimum: 1. Maximum: 1000. Example: `20`. * `learningRate` (_number (double)_) N/A for intent or sentiment models. Example: `0.0001`. * `trainParams` (_string_) JSON that contains parameters that specify how the model is created * `algorithm` (_string_) Algorithm used for train Default: `multilingual-intent`. Example: `multilingual-intent`. #### Responses * **200** Training status Media type: `application/json`. Schema: `TrainResponse`. * **400** Bad request * **404** Resource not found * **502** Unable to complete request due to service error ### POST Train a Dataset `POST /v2/language/train` Operation ID: `train`. Tags: Training (Language). Trains a dataset and creates a model. #### Request Parameters | Name | Type | Description | Available Version | | --- | --- | --- | --- | | `algorithm` | string | Specifies the algorithm used to train the dataset. Optional. Use this parameter only when training a dataset with a type of `text-intent`. Valid values are `intent` (same as `multilingual-intent`, retained for backward compatibility), `multilingual-intent` (supports multiple languages), and `multilingual-intent-ood` (supports multiple languages and handles out-of-domain text). | 2.0 | | `datasetId` | long | ID of the dataset to train. | 2.0 | | `epochs` | int | Number of training iterations for the neural network. Optional. If not specified, the default is calculated based on the dataset size. The larger the number, the longer the training takes to complete. The training process stops before the specified number of epochs if the model has reached the optimal accuracy. When you get the training staus, the `earlyStopping` field specifies whether the training stopped early, and the `lastEpochDone` value specifies the last training iteration. | 2.0 | | `learningRate` | float | N/A for intent or sentiment models. | 2.0 | | `name` | string | Name of the model. Maximum length is 180 characters. | 2.0 | | `trainParams` | object | JSON that contains parameters that specify how the model is created. Optional. Valid values include `{"trainSplitRatio": 0.n}` to specify the ratio of data used to train and test the model, and `{"withGlobalDatasetId": }` to use a global dataset in addition to the specified dataset. | 2.0 | This is an example of the cURL request with parameters. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "name=Weather Intent Model" -F "datasetId=1001411" https://api.einstein.ai/v2/language/train ``` Keep the following points in mind when training a dataset: * If you’re unsure which values to set for the `epochs` and `learningRate` parameters, we recommend that you omit them and use the defaults. * A dataset can have only one training in progress at a time. Let's say you train a dataset and there's a model with a status of `RUNNING` or `QUEUED`. If you attempt to train the same dataset again, you receive an error. * You receive an error when you train a dataset that has more than 3 million words across all examples. Be sure that when you create a dataset or add examples to a dataset, that it contains less than 3 million words. For best results, we recommend that each example is around 100 words. This cURL command sends in the `trainParams` request parameter. This command has double quotes and escaped double quotes around `trainSplitRatio` to run on Windows. You might need to reformat it to run on another OS. ```cURL curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "name=Weather Intent Model" -F "datasetId=1001411" -F "trainParams={\"trainSplitRatio\":0.7}" https://api.einstein.ai/v2/language/train ``` If you want to train a dataset and update an existing model, see Retrain a Dataset. #### Request body Media type: `multipart/form-data`. Schema: `object`. * `datasetId` (_integer (int64)_, required) ID of the dataset to train. Example: `57`. * `epochs` (_integer (int32)_) Number of training iterations for the neural network. Optional. Minimum: 1. Maximum: 1000. Example: `20`. * `learningRate` (_number (double)_) N/A for intent or sentiment models. * `name` (_string_) Name of the model. Maximum length is 180 characters. Minimum length: 0. Maximum length: 180. * `trainParams` (_string_) JSON that contains parameters that specify how the model is created * `algorithm` (_string_) Algorithm used for train Default: `multilingual-intent`. Example: `multilingual-intent`. #### Responses * **200** Training status Media type: `application/json`. Schema: `TrainResponse`. * **400** Bad request * **404** Resource not found * **502** Unable to complete request due to service error ### POST Detect Text `POST /v2/vision/ocr` Operation ID: `ocrMultipart`. Tags: Vision Prediction. Returns a prediction from an OCR model for the specified image URL or local image file. #### Request body Media type: `multipart/form-data`. Schema: `object`. * `modelId` (_string_, required) ID of the model that makes the prediction. Valid values are OCRModel and tabulatev2. Example: `WJH4YCA7YX4PCWVNCYNWYHBMY4`. * `task` (_string_) Optional. Designates the type of data in the image. Default is text. Valid values: contact, table, and text. Default: `text`. Example: `table`. * `sampleId` (_string_) String that you can pass in to tag the prediction. Optional. Can be any value, and is returned in the response. * `sampleContent` (_string (binary)_) Binary content of image file uploaded as multipart/form-data. Optional. * `sampleLocation` (_string_) URL of the image file. Use this parameter when sending in a file from a web location. Optional. #### Responses * **200** OCR result Media type: `application/json`. Schema: `OCRPredictResponse`. * **400** Bad request * **404** Not found #### Code samples _Example: cURL · curl_ ``` curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "modelId=OCRModel" -F "task=table" -F "sampleId=" -F "sampleContent=@" "https://api.einstein.ai/v2/vision/ocr" ``` ### GET Get a Dataset `GET /v2/vision/datasets/{datasetId}` Operation ID: `getDataset_1`. Tags: Vision Prediction. Returns a single dataset. #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` 123456 ``` #### Responses * **200** Success Media type: `application/json`. Schema: `Dataset`. * **404** Not found #### Code samples _Example: cURL · curl_ ``` curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/datasets/" ``` ### DELETE Delete a Dataset `DELETE /v2/vision/datasets/{datasetId}` Operation ID: `deleteDataset_1`. Tags: Vision Prediction. Deletes the specified dataset and associated labels and examples. #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` 123456 ``` #### Responses * **200** Success, deletion job created Media type: `application/json`. Schema: `DeletionResponse`. * **404** Not found #### Code samples _Example: cURL · curl_ ``` curl -X DELETE -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/datasets/" ``` ### GET Get All Examples `GET /v2/vision/datasets/{datasetId}/examples` Operation ID: `getExamples_1`. Tags: Vision Prediction. Returns all the examples for the specified dataset. By default, returns examples created by uploading them from a .zip file. #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` SomeDatasetId ``` * `offset` (query, integer (int32)) Index of the example from which you want to start paging. Default: `0`. * `count` (query, integer (int32)) Number of examples to return. Default: `100`. * `source` (query, string) return examples that were created in the dataset as feedback Allowed values: `all`, `feedback`, `upload`. #### Responses * **200** Success Media type: `application/json`. Schema: `ExampleList`. * **404** Not found #### Code samples _Example: cURL · curl_ ``` curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/datasets//examples" ``` ### GET Get All Examples for Label `GET /v2/vision/examples/{datasetId}/label/{labelId}` Operation ID: `getExamplesByLabel_1`. Tags: Vision Prediction. Returns all the examples for the specified label. Returns both uploaded examples and feedback examples. #### Parameters * `datasetId` (path, integer (int64), required) Dataset Id _Example_ ``` SomeDatasetId ``` * `labelId` (path, integer (int32), required) Label Id _Example_ ``` SomeLabelId ``` * `offset` (query, integer (int32)) Index of the example from which you want to start paging. Default: `0`. * `count` (query, integer (int32)) Number of examples to return. Default: `100`. #### Responses * **200** Success Media type: `application/json`. Schema: `ExampleList`. * **404** Not found #### Code samples _Example: cURL · curl_ ``` curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/examples//label/" ``` ### GET Get All Datasets `GET /v2/vision/datasets` Operation ID: `listDatasets_1`. Tags: Vision Prediction. Returns All datasets. #### Parameters * `count` (query, integer (int32)) Number of datasets to return. Maximum valid value is 25.If you specify a number greater than 25, the call returns 25 datasets. Default: `25`. * `offset` (query, integer (int32)) Index of the dataset from which you want to start paging. Default: `0`. * `global` (query, boolean) If true, returns all global datasets. Global datasets are public datasets that Salesforce provides. Default: `false`. #### Responses * **200** Success Media type: `application/json`. Schema: `DatasetList`. #### Code samples _Example: cURL · curl_ ``` curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/datasets" ``` ### POST Create a Dataset From a Zip File Asynchronously `POST /v2/vision/datasets/upload` Operation ID: `uploadDatasetAsync_1`. Tags: Vision Prediction. Creates a dataset, labels, and examples from the specified specified .zip file. The call returns immediately and continues to upload data in the background. #### Request body Media type: `multipart/form-data`. Schema: `object`. * `data` (_string_) Path to the .zip file on the local drive (FilePart). * `language` (_string_) Dataset language. Optional. Default is N/A. Reserved for future use. Default: `N/A`. * `name` (_string_) Name of the dataset. Optional. If this parameter is omitted, the dataset name is derived from the file name. Example: `mountainvsbeach`. * `path` (_string_) URL of the .zip file. * `type` (_string_, required) Type of dataset data. Allowed values: `image`, `image-detection`, `image-multi-label`. #### Responses * **200** Upload initiated Media type: `application/json`. Schema: `Dataset`. * **400** Bad request #### Code samples _Example: cURL · curl_ ``` curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "data=@" -F "name=" -F "type=image" "https://api.einstein.ai/v2/vision/datasets/upload" ``` ### POST Create a Dataset From a Zip File Synchronously `POST /v2/vision/datasets/upload/sync` Operation ID: `uploadDatasetSync_1`. Tags: Vision Prediction. Creates a dataset, labels, and examples from the specified .zip file. The call returns after the dataset is created and all of the images are uploaded. #### Request body Media type: `multipart/form-data`. Schema: `object`. * `data` (_string_) Path to the .zip file on the local drive (FilePart). * `language` (_string_) Dataset language. Optional. Default is N/A. Reserved for future use. Default: `N/A`. * `name` (_string_) Name of the dataset. Optional. If this parameter is omitted, the dataset name is derived from the .zip file name. Example: `mountainvsbeach`. * `path` (_string_) URL of the .zip file. * `type` (_string_, required) Type of dataset data. Allowed values: `image`, `image-detection`, `image-multi-label`. #### Responses * **200** Upload success Media type: `application/json`. Schema: `Dataset`. #### Code samples _Example: cURL · curl_ ``` curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "data=@" -F "name=" -F "type=image" "https://api.einstein.ai/v2/vision/datasets/upload/sync" ``` ### GET Get Model Metrics `GET /v2/vision/models/{modelId}` Operation ID: `getVisionTrainedModelMetrics`. Tags: Vision Prediction. Returns the metrics for a model #### Parameters * `modelId` (path, string, required) E.ai Platform Model ID _Example_ ``` JBNHFSDAHN3FIFTEQDKCSCDBIA ``` #### Responses * **200** Model metrics Media type: `application/json`. Schema: `Metrics`. * **404** Resource not found * **502** Unable to complete request due to service error #### Code samples _Example: cURL · curl_ ``` curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/models/" ``` ### DELETE Delete a Model `DELETE /v2/vision/models/{modelId}` Operation ID: `deleteVisionModel`. Tags: Vision Prediction. Deletes the specified model. #### Parameters * `modelId` (path, string, required) E.ai Platform Model ID _Example_ ``` JBNHFSDAHN3FIFTEQDKCSCDBIA ``` #### Responses * **201** Deletion submitted Media type: `application/json`. Schema: `DeletionResponse`. * **404** Resource not found * **502** Unable to complete request due to service error #### Code samples _Example: cURL · curl_ ``` curl -X DELETE -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/models/" ``` ### GET Get Training Status `GET /v2/vision/train/{modelId}` Operation ID: `getVisionTrainStatusAndProgress`. Tags: Vision Prediction. Returns the status of a model's training process. Use the progress field to determine how far the training has progressed. When training completes successfully, the status is SUCCEEDED and the progress is 1. #### Parameters * `modelId` (path, string, required) E.ai Platform modelId _Example_ ``` JBNHFSDAHN3FIFTEQDKCSCDBIA ``` #### Responses * **200** Training status Media type: `application/json`. Schema: `TrainResponse`. * **400** Bad request * **404** Resource not found * **502** Unable to complete request due to service error #### Code samples _Example: cURL · curl_ ``` curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/train/" ``` ### GET Get Model Learning Curve `GET /v2/vision/models/{modelId}/lc` Operation ID: `getVisionTrainedModelLearningCurve`. Tags: Vision Prediction. Returns the metrics for each epoch in a model. #### Parameters * `modelId` (path, string, required) E.ai Platform Model ID _Example_ ``` JBNHFSDAHN3FIFTEQDKCSCDBIA ``` * `offset` (query, integer (int32)) Index of the epoch from which you want to start paging Default: `0`. * `count` (query, integer (int32)) Number of epoch to return. Maximum valid value is 25. Default: `25`. #### Responses * **200** Learning curve Media type: `application/json`. Schema: `LearningCurveList`. * **404** Resource not found * **502** Unable to complete request due to service error #### Code samples _Example: cURL · curl_ ``` curl -X GET -H "Authorization: Bearer " -H "Cache-Control: no-cache" "https://api.einstein.ai/v2/vision/models//lc?offset=0&count=25" ``` ### POST Train a Dataset `POST /v2/vision/train` Operation ID: `trainVision`. Tags: Vision Prediction. Trains a dataset and creates a model. #### Request body Media type: `multipart/form-data`. Schema: `object`. * `datasetId` (_integer (int64)_, required) ID of the dataset to train. Example: `57`. * `epochs` (_integer (int32)_) Number of training iterations for the neural network. Optional. Minimum: 1. Maximum: 1000. Example: `20`. * `learningRate` (_number (double)_) N/A when training a detection dataset. * `name` (_string_) Name of the model. Maximum length is 180 characters. Minimum length: 0. Maximum length: 180. * `trainParams` (_string_) JSON that contains parameters that specify how the model is created * `algorithm` (_string_) Algorithm used for train Default: `object-detection-v1`. Example: `object-detection-v1`. #### Responses * **200** Training status Media type: `application/json`. Schema: `TrainResponse`. * **400** Bad request * **404** Resource not found * **502** Unable to complete request due to service error #### Code samples _Example: cURL · curl_ ``` curl -X POST -H "Authorization: Bearer " -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "datasetId=" -F "epochs=20" -F "name=" -F "algorithm=object-detection-v1" "https://api.einstein.ai/v2/vision/train" ``` ## Schemas ### ApiUsageList Api Usage List * `object` (_string_) Object returned; in this case, list. Example: `list`. * `data` (_array of ApiUsage_) ### GenerateAccessTokenResponse * `access_token` (_string_) Access token for authorization. Example: `SPFPQ5IBLB6DPE6FKPWHMIWW4MCRICX4M4KQXFQMI6THZXIEZ6QGNWNOERD6S7655LJAFWTRIKC4KGYO5G3XROMEOTBSS53CFSB6GIA`. * `expires_in` (_string_) Number of seconds that the token will expire from the time it was generated. Example: `120`. * `refresh_token` (_string_) Refresh token that can be used to generate an access token. Only returned when you pass the scope=offline parameter to the endpoint. Example: `FL4GSVQS4W5CKSFRVZBLPIVZZJ2K4VIFPLGZ45SJGUQK4SS56IWPWACZ7V2B7OVLVKZCNK5JZSSW7CIHCNQJAO3TOUE3375108HHTLY`. * `token_type` (_string_) Type of token returned. Always Bearer. Example: `Bearer`. ### ELURequest * `text` (_string_, required) text. * `locale` (_string_) (Optional) Input text language Default: `en_US`. * `timeZone` (_string_) (Optional) Timezone for entities normalization Default: `America/Los_Angeles`. * `context` (_Context_) * `agent` (_integer (int32)_) (Optional) Agent/turn identifier for input text (relevant only if historical 'dialogue' field is set) ### ELUResponse * `sentiment` (_SentimentPredictResponse_) * `intents` (_array of IntentPredictionResponse_) Intents responses * `entities` (_EntitiesPredictResponse_) * `polarity` (_PolarityPredictionResponse_) ### EntitiesPredictRequest * `sampleId` (_string_) String that you can pass in to tag the prediction. Optional. Can be any value, and is returned in the response. * `modelId` (_string_) ID of the model that makes the prediction. Default: `ENTITIES`. * `language` (_string_) Language of the document parameter. Default: `en_US`. * `document` (_string_, required) Text to classify. * `timezone` (_string_) Timezone of user. Default: `America/Los_Angeles`. ### EntitiesPredictResponse * `probabilities` (_array of EntitiesResult_) * `sampleId` (_string_) Value passed in when the prediction call was made. Returned only if the sampleId request parameter is provided. Example: `Sample1`. * `object` (_string_) Object returned; in this case, predictresponse. Example: `predictresponse`. ### PredictionErrorResponse * `message` (_string_) * `object` (_string_) ### IntentPredictRequest * `sampleId` (_string_) String that you can pass in to tag the prediction. Optional. Can be any value, and is returned in the response. * `modelId` (_string_, required) ID of the model that makes the prediction. The model must have been created from a dataset with a type of text-sentiment. Example: `WJH4YCA7YX4PCWVNCYNWYHBMY4`. * `numResults` (_integer (int32)_) Number of probabilities to return. Minimum: 1. Example: `3`. * `document` (_string_, required) Text for which you want to return an intent prediction. Example: `I can't tell you how much fun it was`. ### IntentPredictResponse * `probabilities` (_array of LabelResult_) * `sampleId` (_string_) Value passed in when the prediction call was made. Returned only if the sampleId request parameter is provided. Example: `Sample1`. * `object` (_string_) Object returned; in this case, predictresponse. Example: `predictresponse`. ### SentimentPredictRequest * `sampleId` (_string_) String that you can pass in to tag the prediction. Optional. Can be any value, and is returned in the response. * `modelId` (_string_, required) ID of the model that makes the prediction. The model must have been created from a dataset with a type of text-sentiment. Example: `WJH4YCA7YX4PCWVNCYNWYHBMY4`. * `numResults` (_integer (int32)_) Number of probabilities to return. Minimum: 1. Example: `3`. * `document` (_string_, required) Text for which you want to return a sentiment prediction. Example: `I can't tell you how much fun it was`. ### SentimentPredictResponse * `probabilities` (_array of LabelResult_) * `sampleId` (_string_) Value passed in when the prediction call was made. Returned only if the sampleId request parameter is provided. Example: `Sample1`. * `object` (_string_) Object returned; in this case, predictresponse. Example: `predictresponse`. ### Dataset * `id` (_integer (int64)_) Dataset ID. Example: `1000014`. * `name` (_string_) Name of the dataset. Example: `weather report`. * `createdAt` (_string (date-time)_) Date and time that the dataset was created. * `updatedAt` (_string (date-time)_) Date and time that the dataset was last updated. * `labelSummary` (_LabelSummary_) * `totalExamples` (_integer (int32)_) Total number of examples in the dataset. Example: `20`. * `totalLabels` (_integer (int32)_) Total number of labels in the dataset. Example: `2`. * `available` (_boolean_) Specifies whether the dataset is ready to be trained. * `statusMsg` (_string_) Status of the dataset creation and data upload. Example: `SUCCEEDED`. * `type` (_string_) Type of dataset data. * `language` (_string_) Dataset language. Example: `N/A`. * `numOfDuplicates` (_integer (int32)_) Number of duplicate images. This number includes duplicates in the .zip file from which the dataset was created plus the number of duplicate images from subsequent PUT calls to add images to the dataset. * `entityName` (_string_) * `filter` (_string_) * `changesetId` (_integer (int32)_) Changeset ID. Example: `1`. * `object` (_string_) Object returned; in this case, dataset. Example: `dataset`. ### DeletionResponse * `deletedObjectId` (_string_) ID of the object deleted. Depending on the object you delete, this contains the dataset ID or the model ID. Example: `1003360`. * `id` (_string_) ID of the deletion Example: `Z2JTFBF3A7XKIJC5QEJXMO4HSY`. * `message` (_string_) Additional information about the deletion. For example, a message is returned if the deletion fails. * `organizationId` (_string_) ID of the org to which the dataset or model being deleted belongs. Example: `2`. * `progress` (_number (double)_) How far the deletion has progressed. Values are between 0–1. Example: `1`. * `status` (_string_) Status of the deletion. Allowed values: `QUEUED`, `RUNNING`, `SUCCEEDED_WAITING_FOR_CACHE_REMOVAL`, `SUCCEEDED`, `KILLED`, `FAILED`, `RETRY`. * `type` (_string_) Object that's being deleted Allowed values: `DATASET`, `MODEL`. * `object` (_string_) Object returned; in this case, deletion. Example: `deletion`. ### ExampleList * `object` (_string_) Object returned; in this case, list. Example: `list`. * `data` (_array of Example_) ### ModelList * `object` (_string_) Object returned; in this case, list. Example: `list`. * `data` (_array of TrainedModelResponse_) ### DatasetList * `object` (_string_) Object returned; in this case, list. Example: `list`. * `data` (_array of Dataset_) ### Metrics * `id` (_string_) Model Id * `metricsData` (_string_) Model metrics values. * `createdAt` (_string (date-time)_) Date and time that the model was created. * `language` (_string_) * `algorithm` (_string_) * `object` (_string_) ### TrainResponse * `datasetId` (_integer (int64)_) ID of the dataset trained to create the model. Example: `57`. * `datasetVersionId` (_integer (int64)_) Not available yet Example: `0`. * `name` (_string_) Name of the model. Example: `My Model - Version1`. * `status` (_string_) Status of the model. Allowed values: `QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `KILLED`, `FAILED_WITH_RETRIES`. * `progress` (_number_) How far the dataset training has progressed. Values are between 0–1. Example: `0.7`. * `createdAt` (_string (date-time)_) Date and time that the model was created. * `updatedAt` (_string (date-time)_) Date and time that the model was last updated. * `modelId` (_string_) ID of the model. Contains letters and numbers. Example: `2KXJEOM3N562JBT4P7OX7VID2Q`. * `hawkingModelArtifactId` (_string_) * `failureMsg` (_string_) Reason the dataset training failed. Returned only if the training status is FAILED. Example: `To train a dataset and create a model, the dataset must contain at least 100 examples per label for test set`. * `learningRate` (_number (double)_) Learning rate used during training. Example: `0.0001`. * `epochs` (_integer (int32)_) Number of epochs used during training. Example: `20`. * `queuePosition` (_integer (int32)_) Where the training job is in the queue. This field appears in the response only if the status is QUEUED. Example: `1`. * `modelType` (_string_) Type of data from which the model was created. * `algorithm` (_string_) Algorithm used to create the model. Returned only when the modelType is image-detection. Example: `object-detection`. * `language` (_string_) Model language inherited from the dataset language. For image datasets, default is N/A. For text datasets, default is en\_US. Example: `en_US`. * `object` (_string_) Object returned; in this case, training. Example: `training`. * `trainParams` (_string_) Training parameters passed into the request. Example: `{"trainSplitRatio":0.7}`. * `trainStats` (_string_) Returns null when you train a dataset. Training statistics are returned when the status is SUCCEEDED or FAILED. ### LearningCurveList * `object` (_string_) Object returned; in this case, list. Example: `list`. * `data` (_array of LearningCurve_) ### OCRPredictResponse * `object` (_string_) Object returned; in this case, predictresponse. Example: `predictresponse`. * `probabilities` (_array of OCRResult_) * `task` (_string_) Same value as request parameter. Returns text if the request parameter isn't supplied. Example: `Task1`. * `sampleId` (_string_) Same value as request parameter. Returned only if the sampleId request parameter is provided. Example: `Sample1`. ### ApiUsage * `id` (_integer (int64)_, required) Id Example: `489`. * `organizationId` (_string_, required) Organization Id Example: `108`. * `type` (_string_, required) Type * `count` (_integer (int64)_, required) Count * `planData` (_array of PlanData_, required) Plan Data as Json * `startsAt` (_string (date-time)_, required) Starts At Example: `2017-03-01T00:00:00Z`. * `endsAt` (_string (date-time)_, required) Ends At Example: `2017-04-01T00:00:00Z`. * `licenseId` (_string_, required) License ID Example: `kJCHtYDCSf`. * `predictionsRemaining` (_integer (int32)_, required) Predictions Remaining Example: `1997`. * `predictionsUsed` (_integer (int32)_, required) Predictions Used Example: `3`. * `predictionsMax` (_integer (int32)_, required) Predictions Max Example: `2000`. * `object` (_string_, required) object Example: `apiusage`. ### Context (Optional) Context * `models` (_array of ELUModel_) List of models to be used Minimum items: 0. Maximum items: 3. * `dialogue` (_array of Utterance_) (Optional) History of the current conversation Minimum items: 0. Maximum items: 5. ### IntentPredictionResponse Intents responses * `probabilities` (_array of LabelResult_) * `sampleId` (_string_) Value passed in when the prediction call was made. Returned only if the sampleId request parameter is provided. Example: `Sample1`. * `object` (_string_) Object returned; in this case, predictresponse. Example: `predictresponse`. * `model` (_ELUModel_) ### PolarityPredictionResponse Polarity responses * `probabilities` (_array of LabelResult_) ### EntitiesResult Array of probabilities for the prediction. * `token` (_string_, required) Characters from the document parameter to which the returned label applies * `label` (_string_, required) Probability label for the input * `probability` (_number (float)_, required) Probability value for the input. Values are between 0–1 * `span` (_Span_, required) * `normalizedData` (_array of NormalizedValue_, required) Normalization values for the entity. The format differs based on the normalization type (one of person, range or string) ### LabelResult label * `probability` (_number (float)_) Probability value for the input. Values are between 0–1. * `label` (_string_) Probability label for the input. ### LabelSummary Contains the labels array that contains all the labels for the dataset. * `labels` (_array of Label_) ### Example * `id` (_integer (int64)_, required) ID of the example. Example: `546`. * `name` (_string_, required) Name of the example. Example: `659803277.jpg`. * `location` (_string_) Location of the image in the dataset. Example: `1798f7e1f628a22f450c50c17247b314b392296758581ec688ea418b8a413df71.jpg`. * `createdAt` (_string (date-time)_) Date and time that the example was created. * `label` (_Label_) * `object` (_string_) Object returned; in this case, example. Example: `example`. ### TrainedModelResponse * `object` (_string_) Object returned; in this case, model. Example: `model`. * `modelId` (_string_) E.ai Model ID. Example: `13JK34JJ44`. * `hawkingModelId` (_string_) Hawking model ID. Example: `sdfas324234`. * `hawkingPipelineArtifactId` (_string_) Hawking pipeline artifact ID. Example: `sdfjksdajflkasdjf`. * `createdAt` (_string (date-time)_) Date and time that the model was created. * `updatedAt` (_string (date-time)_) Date and time that the model was last updated. * `datasetId` (_integer (int64)_) Eai dataset ID Example: `6000059`. * `hawkingTrainingFlowId` (_string_) Hawking training flow ID Example: `5923c823-e7f1-4f1d-b3c6-61450cae697a`. * `hawkingPipelineRunId` (_string_) Hawking pipeline run ID Example: `5923c823-e7f1-4f1d-b3c6-61450cae697a_1`. * `name` (_string_) Name of the model Example: `Weather Intent Model`. * `status` (_string_) status of model Allowed values: `QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `KILLED`, `FAILED_WITH_RETRIES`. Example: `QUEUED`. * `progress` (_number_) progress of model Example: `0.7`. ### LearningCurve * `object` (_string_) Object returned; in this case, learningcurve. Example: `learningcurve`. * `epoch` (_object_) Epoch to which the metrics correspond. Example: `1`. * `metricsData` (_object_) Model metrics values. * `epochResults` (_object_) Prediction results for the set of data used to test the model during training. ### OCRResult Array of probabilities for the prediction. * `probability` (_number (float)_) Probability value for the input. Values are between 0–1. * `label` (_string_) Content of the detected text. * `boundingBox` (_BoundingBox_) * `attributes` (_Attributes_) ### PlanData Plan Data as Json * `plan` (_string_) Example: `STARTER`. * `amount` (_integer (int32)_) Example: `1`. * `source` (_string_) Example: `HEROKU`. ### ELUModel Models definition to consume for Insights * `id` (_string_, required) id * `type` (_string_, required) type Allowed values: `intents`, `entities`, `co-references`, `negation`, `sentiment`, `polarity`, `slots`. * `numResults` (_integer (int32)_) numResults ### Utterance One turn of a conversation * `agent` (_integer (int32)_, required) Agent id * `text` (_string_, required) Input document ### Span Contains the starting character position and ending character position of the token with the document string * `end` (_integer (int32)_, required) end * `start` (_integer (int32)_, required) start ### NormalizedValue Normalization values for the entity. The format differs based on the normalization type (one of person, range or string) * `firstName` (_string_) Person's first name if detected. * `lastName` (_string_) Person's last name if detected. * `middleName` (_string_) Person's middle name if detected. * `salutation` (_string_) Person's salutation if detected. * `suffix` (_string_) Person's suffix if detected. * `from` (_NormalizedString_) * `to` (_NormalizedString_) * `unit` (_string_) Unit of measure. Can be empty. * `value` (_string_) Entity value normalized to a standard format. * `issuer` (_string_) credit card issuer * `type` (_string_) Type of normalization. Use this to interpret the normalized data ### Label * `id` (_integer (int64)_) ID of the label. Example: `621`. * `datasetId` (_integer (int64)_, required) ID of the dataset that the label belongs to. Example: `57`. * `name` (_string_, required) Name of the label. Example: `Mountain`. * `numExamples` (_integer (int64)_) Number of examples that have the label. Example: `40`. ### BoundingBox * `x1` (_integer (int32)_, write-only) * `y1` (_integer (int32)_, write-only) * `x2` (_integer (int32)_, write-only) * `y2` (_integer (int32)_, write-only) * `minX` (_integer (int32)_) X-coordinate of the right side of the bounding box. Number of pixels from the left edge of the image. * `minY` (_integer (int32)_) Y-coordinate of the bottom of the bounding box. Number of pixels from the top edge of the image. * `maxX` (_integer (int32)_) X-coordinate of the left side of the bounding box. The origin of the coordinate system is the top-left of the image. Number of pixels from the left edge of the image. * `maxY` (_integer (int32)_) Y-coordinate of the top of the bounding box. Number of pixels from the top edge of the image. ### Attributes Contains additional attributes related to the task parameter. If the task parameter is table, the row and column IDs for the detected text are returned. If the task parameter is contact, the detected entity tags will be returned. * `cell` (_CellLocation_) * `tag` (_string_) * `language` (_string_) * `value` (_EntityObject_) * `pageBlockType` (_string_, write-only) * `pageObjectUnit` (_array of PageObjectUnit_, write-only) * `pageNumber` (_string_) * `tableId` (_string_) * `cellLocation` (_CellLocation_) ### NormalizedString Type of normalization. Use this to interpret the normalized data * `unit` (_string_) Unit of measure. Can be empty. * `value` (_string_) Entity value normalized to a standard format. * `type` (_string_) type ### CellLocation * `rowIndex` (_integer (int32)_) Index of the row that contains the detected text. * `colIndex` (_integer (int32)_) Index of the column that contains the detected text. ### EntityObject * `text` (_string_) * `entity` (_string_) * `boundingBox` (_BoundingBox_) * `normalizedText` (_string_) ### PageObjectUnit * `text` (_string_) * `boundingBox` (_BoundingBox_) * `pageObjectUnitAttributes` (_PageObjectUnitAttributes_) ### PageObjectUnitAttributes * `bold` (_boolean_) * `cell` (_CellLocation_) * `cellLocation` (_CellLocation_)