Help Center> Natural Language Processing> API Reference> NLP APIs> MT APIs> Document Translation Job Creation
View PDF

Document Translation Job Creation

Introduction

Translating documents takes a long time, so the translation process is asynchronous. That is, two APIs are involved, API for creating translation jobs (job creation API) and API for querying job status (job status query API).

After the job creation API is called and returns the result, you can call the job status query API to obtain the translation status and temporary URL. You can use the temporary URL to download translated documents. Each temporary URL keeps valid for 10 minutes. The translation result is stored for 24 hours (starting from the time when the translation is completed). If you access the result after 24 hours, an error message indicating task id is not found is returned.

The document translation API belongs to MT APIs. Currently, MT is in commercial use. Therefore, calling MT APIs will incur fees. You can learn about the pricing details in NLP Price Calculator.

The job creation API is used to create and submit a document translation job. Documents to be translated are stored in an OBS bucket. To call this API, you must have the permission to read the OBS bucket. For details about the configurations, see Configuring Access Permissions of OBS.

For details about document translation endpoints, see Endpoints.

URI

  • URI format 
    POST /v1/{project_id}/machine-translation/file-translation/jobs
  • Parameter description
    Table 1 URI parameters

    Parameter

    Mandatory

    Description

    project_id

    Yes

    Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Request

Table 2 describes the request parameters.
Table 2 Request parameters

Parameter

Type

Mandatory

Description

url

String

Yes

Path of the document stored on OBS. You are advised to use the temporarily authorized URL to download private documents. For details about how to obtain the document URL on OBS and the temporarily authorized URL, see Configuring Access Permissions of OBS. The region of OBS must be the same as that of the requested service. Otherwise, OBS is unavailable, even if it allows public access. The name of the document stored on OBS must be letters.

from

String

Yes

Source language. Currently, Chinese and English are supported.

to

String

Yes

Target language. Currently, Chinese and English are supported.

type

String

Yes

Document format. Currently, docx, pptx, and txt files can be translated.
Table 3 Supported languages

Language (from)

Language (to)

Description

zh

en

Translation from Chinese to English

en

zh

Translation from English to Chinese

Response

Table 4 describes the response parameters.
Table 4 Response parameters

Parameter

Type

Description

job_id

String

ID of the job to be created. This parameter is mandatory when a job is successfully created. This parameter is not included when a job fails to be created.

error_code

String

For details, see the error code list. This parameter is not included when the API is successfully called.

error_msg

String

Returned error message. This parameter is not included when the API is successfully called.

Example

  • Example request 
    POST https://{endpoint}/v1/{project_id}/machine-translation/file-translation
Request Header:  
    Content-Type:application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...   

Request Body:
    {
        "url": "https://****.obs.cn-north-4.huawei.com/***.docx", 
        "from": "zh", 
        "to": "en",
        "type":"docx"
    }
  • Successful example response 
    {
    "job_id": "567e6536-****-****-****-826321939656"
}
  • Failed example response 
    {
    "error_code": "NLP.0101",
    "error_msg": "Authentication failed. Verify the token."
}
Parent topic: MT APIs