{ "openapi": "3.0.0-RC1", "servers": [ { "url": "https://gateway.watsonplatform.net/language-translator/api" } ], "info": { "version": "2.0.0", "title": "Language Translator", "description": "Language Translator translates text from one language to another. The service offers multiple domain-specific models that you can customize based on your unique terminology and language. Use Language Translator to take news from across the globe and present it in your language, communicate with your customers in their own language, and more." }, "security": [ { "basicAuth": [] } ], "paths": { "/v2/models": { "get": { "tags": ["models"], "operationId": "listModels", "summary": "Lists available standard and custom models by source or target language", "description": "", "parameters": [ { "name": "source", "in": "query", "description": "Filter models by source language.", "required": false, "schema": { "type": "string" } }, { "name": "target", "in": "query", "description": "Filter models by target language.", "required": false, "schema": { "type": "string" } }, { "name": "default", "in": "query", "description": "Valid values are leaving it unset, `true`, and `false`. When `true`, it filters models to return the default model or models. When `false`, it returns the non-default model or models. If not set, it returns all models, default and non-default.", "required": false, "x-alternate-name": "default_models", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationModels" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": ["models"], "operationId": "createModel", "summary": "Uploads a TMX glossary file on top of a domain to customize a translation model", "description": "", "parameters": [ { "name": "base_model_id", "in": "query", "description": "Specifies the domain model that is used as the base for the training. To see current supported domain models, use the GET /v2/models parameter.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "The model name. Valid characters are letters, numbers, -, and _. No spaces.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success: Training is successfully started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationModel" } } } }, "400": { "description": "Bad request: The base_model_id is not specified OR you've hit the maximum limit of customizations for this user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found: The base_model_id value is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "File size exceeded: Payload body exceeded the limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v2/models/{model_id}": { "delete": { "tags": ["models"], "operationId": "deleteModel", "summary": "Deletes a custom translation model", "description": "", "parameters": [ { "name": "model_id", "in": "path", "description": "The model identifier.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success: Model deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteModelResult" } } } }, "400": { "description": "Unauthorized: This model was created by IBM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found: The specified model_id was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": ["models"], "operationId": "getModel", "summary": "Returns the training status of the translation model", "description": "", "parameters": [ { "name": "model_id", "in": "path", "description": "Model ID to use", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status : OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/translate": { "get": { "tags": ["translate"], "operationId": "translateGet", "summary": "Translates the input text from the source language to the target language", "description": "", "parameters": [ { "name": "model_id", "in": "query", "description": "The unique model_id of the translation model that is used to translate text. The model_id inherently specifies source language, target language, and domain. If the model_id is specified, there is no need for the source and target parameters, and the values are ignored.", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Used in combination with target as an alternative way to select the model for translation. When target and source are set, and model_id is not set, the system chooses a default model with the right language pair to translate (usually the model based on the news domain).", "required": false, "schema": { "type": "string" } }, { "name": "target", "in": "query", "description": "Used in combination with source as an alternative way to select which model is used for translation. When target and source are set, and model_id is not set, the system chooses a default model with the right language pair to translate (usually the model based on the news domain).", "required": false, "schema": { "type": "string" } }, { "name": "text", "in": "query", "description": "Input text in UTF-8 encoding. Multiple text query parameters indicate multiple input paragraphs, and a single string is valid input.", "required": true, "schema": { "type": "string" } }, { "name": "accept", "in": "header", "description": "Describes the format of the return values. Valid values are “text/plain” (default), or “application/json”.", "required": false, "schema": { "type": "string", "enum": ["application/json", "text/plain"], "default": "text/plain" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Translation" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/Translation" } } } }, "400": { "description": "Bad Request: missing required parameter(s)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model Not Found: the specified model_id does not exist or specified source - target language pair is not supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-exclude": true }, "post": { "tags": ["translate"], "operationId": "translate", "summary": "Translates the input text from the source language to the target language", "description": "", "parameters": [ { "name": "accept", "in": "header", "description": "Describes the format of the return values.", "required": false, "schema": { "type": "string", "enum": ["application/json", "text/plain"], "default": "text/plain" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Translation" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/Translation" } } } }, "400": { "description": "Bad Request: missing required parameter(s)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model Not Found: the specified model_id does not exist or specified source - target language pair is not supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateRequest" } } }, "description": "The translate request containing the text, with optional source, target, and model_id.", "required": true } } }, "/v2/identifiable_languages": { "get": { "tags": ["identify"], "operationId": "listIdentifiableLanguages", "summary": "Lists all languages that can be identified by the API", "description": "Lists all languages that the service can identify. Returns the two-letter code (for example, `en` for English or `es` for Spanish) and name of each language.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportedLanguages" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/identify": { "get": { "tags": ["identify"], "operationId": "identifyGet", "summary": "Identifies the language of the input text.", "parameters": [ { "name": "text", "in": "query", "description": "Input text in UTF-8 format.", "required": true, "schema": { "type": "string" } }, { "name": "accept", "in": "header", "description": "Describes the format of the return values. By default, the return type is `text/plain` and the return value is the two-letter language code for the identified language, for example, `en` for English or `es` for Spanish. To retrieve a JSON object containing a ranking of identified languages with confidence scores, set the accept header parameter to `application/json`.", "required": false, "schema": { "type": "string", "enum": ["application/json", "text/plain"], "default": "text/plain" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/Languages" } } }, "links": { "translation": { "$ref": "#/components/links/Translation" } } }, "400": { "description": "Bad Request: missing required text parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-exclude": true }, "post": { "tags": ["identify"], "operationId": "identify", "summary": "Identifies the language of the input text.", "parameters": [ { "name": "accept", "in": "header", "description": "Describes the format of the return values. By default, the return type is `text/plain` and the return value is the two-letter language code for the identified language, for example, `en` for English or `es` for Spanish. To retrieve a JSON object that contains a ranking of identified languages with confidence scores, set the accept header parameter to `application/json`.", "required": false, "schema": { "type": "string", "enum": ["application/json", "text/plain"], "default": "text/plain" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/Languages" } } } }, "400": { "description": "Bad Request: missing required input text in request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Input text in UTF-8 format.", "required": true } } } }, "components": { "schemas": { "TranslationModels": { "description": "The response type for listing existing translation models.", "properties": { "models": { "description": "An array of available models.", "type": "array", "items": { "$ref": "#/components/schemas/TranslationModel" } } } }, "TranslationModel": { "description": "Response payload for models.", "properties": { "model_id": { "description": "A globally unique string that identifies the underlying model that is used for translation. This string contains all the information about source language, target language, domain, and various other related configurations.", "type": "string" }, "name": { "description": "If a model is trained by a user, there might be an optional “name” parameter attached during training to help the user identify the model.", "type": "string" }, "source": { "description": "Source language in two letter language code. Use the five letter code when clarifying between multiple supported languages. When model_id is used directly, it will override the source-target language combination. Also, when a two letter language code is used, but no suitable default is found, it returns an error.", "type": "string" }, "target": { "description": "Target language in two letter language code.", "type": "string" }, "base_model_id": { "description": "If this model is a custom model, this returns the base model that it is trained on. For a base model, this response value is empty.", "type": "string" }, "domain": { "description": "The domain of the translation model.", "type": "string" }, "customizable": { "description": "Whether this model can be used as a base for customization. Customized models are not further customizable, and we don't allow the customization of certain base models.", "type": "boolean" }, "default_model": { "description": "Whether this model is considered a default model and is used when the source and target languages are specified without the model_id.", "type": "boolean" }, "owner": { "description": "Returns the Bluemix ID of the instance that created the model, or an empty string if it is a model that is trained by IBM.", "type": "string" }, "status": { "description": "Availability of a model.", "type": "string", "enum": [ "uploading", "uploaded", "dispatching", "queued", "training", "trained", "publishing", "available", "deleted", "error" ] } } }, "DeleteModelResult": { "required": ["status"], "properties": { "status": { "description": "\"OK\" indicates that the model was successfully deleted.", "type": "string" } } }, "TranslateRequest": { "required": ["text"], "properties": { "model_id": { "description": "The unique model_id of the translation model being used to translate text. The model_id inherently specifies source language, target language, and domain. If the model_id is specified, there is no need for the source and target parameters and the values are ignored.", "type": "string" }, "source": { "description": "Used in combination with target as an alternative way to select the model for translation. When target and source are set, and model_id is not set, the system chooses a default model with the right language pair to translate (usually the model based on the news domain).", "type": "string" }, "target": { "description": "Used in combination with source as an alternative way to select the model for translation. When target and source are set, and model_id is not set, the system chooses a default model with the right language pair to translate (usually the model based on the news domain).", "type": "string" }, "text": { "description": "Input text in UTF-8 encoding. It is a list so that multiple sentences/paragraphs can be submitted. Also accept a single string, instead of an array, as valid input.", "type": "array", "items": { "type": "string" } } } }, "Translation": { "required": ["word_count", "character_count", "translations"], "properties": { "word_count": { "description": "Number of words of the complete input text.", "type": "integer" }, "character_count": { "description": "Number of characters of the complete input text.", "type": "integer" }, "translations": { "description": "List of translation output in UTF-8, corresponding to the list of input text.", "type": "array", "items": { "$ref": "#/components/schemas/TranslationText" } } } }, "TranslationText": { "required": ["translation"], "properties": { "translation": { "description": "Translation output in UTF-8.", "type": "string" } } }, "SupportedLanguages": { "required": ["languages"], "properties": { "languages": { "description": "A list of all languages that the service can identify.", "type": "array", "items": { "$ref": "#/components/schemas/IdentifiableLanguage" } } } }, "IdentifiableLanguage": { "required": ["language", "name"], "properties": { "language": { "description": "The code for an identifiable language.", "type": "string" }, "name": { "description": "The name of the identifiable language.", "type": "string" } } }, "Languages": { "required": ["languages"], "properties": { "languages": { "description": "A ranking of identified languages with confidence scores.", "type": "array", "items": { "$ref": "#/components/schemas/IdentifiedLanguage" } } } }, "IdentifiedLanguage": { "required": ["language", "confidence"], "properties": { "language": { "description": "The code for an identified language.", "type": "string" }, "confidence": { "description": "The confidence score for the identified language.", "type": "number", "format": "double", "minimum": 0, "maximum": 1 } } }, "ErrorResponse": { "required": ["error_code", "error_message"], "properties": { "error_code": { "description": "A short identifier for the error.", "type": "string" }, "error_message": { "description": "A more detailed description of the error.", "type": "string" } } } }, "responses": {}, "parameters": {}, "examples": {}, "requestBodies": {}, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "headers": {}, "links": { "Translation": { "operationId": "translateGet", "parameters": { "source": "$response.body#/languages[0].language", "text": "$request.query.text" }, "description": "Translates the text with the highest language identified with the highest confidence." } } } }