Operations for translating documents
openapi: 3.0.3
info:
title: IBM Watson Language Translator V3 Documents API
description: 'REST API for translating text between 35+ languages, identifying the language of input text, listing available translation models, and creating or managing custom translation models. The base URL varies by region. IAM authentication via Bearer tokens is required. The API version parameter 2018-05-01 is required on all requests. NOTE: This service was deprecated in June 2023 and withdrawn in December 2024.'
version: 3.0.0
contact:
name: IBM Watson
url: https://cloud.ibm.com/apidocs/language-translator
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
x-deprecated: true
x-deprecation-date: '2023-06-01'
x-withdrawal-date: '2024-12-01'
servers:
- url: https://api.us-south.language-translator.watson.cloud.ibm.com
description: US South
- url: https://api.us-east.language-translator.watson.cloud.ibm.com
description: US East
- url: https://api.eu-de.language-translator.watson.cloud.ibm.com
description: Frankfurt (EU)
- url: https://api.eu-gb.language-translator.watson.cloud.ibm.com
description: London (EU)
- url: https://api.au-syd.language-translator.watson.cloud.ibm.com
description: Sydney
- url: https://api.jp-tok.language-translator.watson.cloud.ibm.com
description: Tokyo
- url: https://api.kr-seo.language-translator.watson.cloud.ibm.com
description: Seoul
security:
- BearerAuth: []
tags:
- name: Documents
description: Operations for translating documents
paths:
/v3/documents:
get:
summary: List documents
description: Lists documents that have been submitted for translation. Returns a list of documents with supporting meta data.
operationId: listDocuments
tags:
- Documents
parameters:
- $ref: '#/components/parameters/Version'
responses:
'200':
description: Successful response with list of submitted documents
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentList'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
post:
summary: Translate document
description: Submit a document for translation. You can submit the document contents in the file parameter, and optionally the name of the document in the filename parameter. Specify the translation model to use for translation of the document contents by either providing a model ID using the model_id parameter or the source and target language code using the source and target parameters. IBM Watson Language Translator may reject documents submission requests if the file size limit is exceeded. The current size limit for document translation is 20 MB.
operationId: translateDocument
tags:
- Documents
parameters:
- $ref: '#/components/parameters/Version'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: The contents of the source file to translate.
filename:
type: string
description: The name of the input file in UTF-8 format, including the file extension. Used when providing a filename is needed.
file_content_type:
type: string
description: The content type of the file.
model_id:
type: string
description: The model to use for translation. model_id or both source and target is required.
source:
type: string
description: Language code that specifies the language of the source document.
target:
type: string
description: Language code that specifies the language for translation output.
document_id:
type: string
description: To use a previously submitted document as the source for a new translation, enter the document_id of the document.
responses:
'202':
description: Document accepted for translation
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentStatus'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'413':
$ref: '#/components/responses/PayloadTooLarge'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'500':
$ref: '#/components/responses/InternalServerError'
/v3/documents/{document_id}:
get:
summary: Get document status
description: Gets the translation status of a document. Returns the current status of a document translation. This method has to be invoked multiple times to determine when the translation has completed.
operationId: getDocumentStatus
tags:
- Documents
parameters:
- $ref: '#/components/parameters/Version'
- name: document_id
in: path
required: true
description: The document ID of the document to retrieve status of.
schema:
type: string
responses:
'200':
description: Successful response with document translation status
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentStatus'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
summary: Delete document
description: Deletes a document.
operationId: deleteDocument
tags:
- Documents
parameters:
- $ref: '#/components/parameters/Version'
- name: document_id
in: path
required: true
description: Document ID of the document to delete.
schema:
type: string
responses:
'204':
description: Document deleted successfully (no content returned)
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v3/documents/{document_id}/translated_document:
get:
summary: Get translated document
description: Gets the translated document associated with the given document ID. Returns the translated document in the same format as the original source file. You must check that the translation is complete before calling this method. You can use the Get document status method to check the translation status.
operationId: getTranslatedDocument
tags:
- Documents
parameters:
- $ref: '#/components/parameters/Version'
- name: document_id
in: path
required: true
description: The document ID of the document that was submitted for translation.
schema:
type: string
- name: Accept
in: header
description: The type of the response. Match the file type of the source file.
schema:
type: string
responses:
'200':
description: Translated document binary response
content:
application/powerpoint:
schema:
type: string
format: binary
application/mspowerpoint:
schema:
type: string
format: binary
application/msword:
schema:
type: string
format: binary
application/vnd.openxmlformats-officedocument.presentationml.presentation:
schema:
type: string
format: binary
application/vnd.openxmlformats-officedocument.wordprocessingml.document:
schema:
type: string
format: binary
application/vnd.ms-powerpoint:
schema:
type: string
format: binary
application/pdf:
schema:
type: string
format: binary
text/html:
schema:
type: string
text/plain:
schema:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
NotFound:
description: Not found - resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
PayloadTooLarge:
description: Payload too large - file exceeds size limit
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Forbidden - insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Unauthorized - invalid or missing credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
UnsupportedMediaType:
description: Unsupported media type - file format not supported
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Bad request - invalid input parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
DocumentList:
type: object
description: DocumentList contains the list of documents with status.
properties:
documents:
type: array
description: An array of all previously submitted documents.
items:
$ref: '#/components/schemas/DocumentStatus'
ErrorResponse:
type: object
description: Error response object.
properties:
code:
type: integer
description: HTTP status code.
example: 400
error:
type: string
description: Human-readable error description.
example: Bad request
description:
type: string
description: Detailed description of the error.
DocumentStatus:
type: object
description: Information about the submitted document and the translation process.
properties:
document_id:
type: string
description: System generated ID identifying a document being translated using one specific translation model.
example: abc123
filename:
type: string
description: filename included in the request or extracted from the file name.
example: report.docx
status:
type: string
description: 'The status of the translation job associated with a submitted document. Valid values are: processing, available, failed, deleted.'
enum:
- processing
- available
- failed
- deleted
example: available
model_id:
type: string
description: A globally unique string that identifies the underlying model that is used for translation.
example: en-es
base_model_id:
type: string
description: Model ID of the base model that was used to customize the model. If the model is not a custom model, this will be an empty string.
example: en-es
source:
type: string
description: Translation source language code.
example: en
detected_language_confidence:
type: number
format: double
description: The confidence score for the source language identification. Returned only when the model used automatic language identification.
minimum: 0
maximum: 1
example: 0.998
target:
type: string
description: Translation target language code.
example: es
created:
type: string
format: date-time
description: The time when the document was submitted.
completed:
type: string
format: date-time
description: The time when the translation completed (available or failed).
word_count:
type: integer
description: The number of words in the source document.
example: 523
character_count:
type: integer
description: The number of characters in the source document, present only if available.
example: 3142
parameters:
Version:
name: version
in: query
required: true
description: Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-05-01.
schema:
type: string
example: '2018-05-01'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: IBM Cloud IAM token authentication
externalDocs:
description: IBM Cloud API Docs - Language Translator
url: https://cloud.ibm.com/apidocs/language-translator